@kennyzhao/cgm 0.0.0-stage → 1.0.0

package/DEPLOY-Linux.md

@@ -0,0 +1,75 @@
+# CodeGraph Manager —— 服务器部署说明
+
+一个带前端界面的服务，管理服务器上"GitLab 仓库 → clone → codegraph 分析 → 移除"的完整闭环。
+零依赖：只需 Node.js + git + codegraph。
+
+## 一条命令跑起来（Linux）
+
+```bash
+# 依赖检查
+node -v && git --version
+# codegraph（任选安装方式）
+curl -fsSL https://raw.githubusercontent.com/colbymchenry/codegraph/main/install.sh | sh
+codegraph --version
+
+# 拉工程、起服务
+cd /opt && git clone <你的仓库> codegraph-manager   # 或 scp server.mjs + public/
+cd codegraph-manager
+HOST=127.0.0.1 PORT=8801 DATA_DIR=/var/lib/codegraph-manager \
+  node server.mjs
+```
+
+## 环境变量
+
+| 变量 | 默认 | 说明 |
+|---|---|---|
+| `HOST` | `127.0.0.1` | 监听地址。只本机管理就默认；**要团队网页访问改 `0.0.0.0` + 设 ADMIN_TOKEN** |
+| `PORT` | `8801` | 端口 |
+| `DATA_DIR` | `./data` | `settings.json`(含 GitLab token) + `repos.json` 存放 |
+| `ADMIN_TOKEN` | 空 | 可选 Bearer 令牌，保护页面/API |
+| `CODEGRAPH_BIN` | `codegraph` | codegraph 调用方式：`codegraph`、`/usr/local/bin/codegraph`、或 **JSON 数组**（含空格路径时用，如 `["node","/opt/.../npm-shim.js"]`） |
+
+## systemd 常驻
+
+`/etc/systemd/system/codegraph-manager.service`：
+```ini
+[Unit]
+Description=CodeGraph Manager
+After=network.target
+
+[Service]
+Type=simple
+WorkingDirectory=/opt/codegraph-manager
+Environment=HOST=127.0.0.1
+Environment=PORT=8801
+Environment=DATA_DIR=/var/lib/codegraph-manager
+Environment=CODEGRAPH_BIN=/usr/local/bin/codegraph
+# GitLab appkey 不进 unit，从界面保存后落在 DATA_DIR/settings.json
+ExecStart=/usr/bin/node server.mjs
+Restart=always
+User=codegraph
+Group=codegraph
+
+[Install]
+WantedBy=multi-user.target
+```
+```bash
+systemctl daemon-reload && systemctl enable --now codegraph-manager
+```
+
+## 使用流程（界面 http://<host>:8801）
+1. **GitLab 配置**：填 GitLab 地址 + AppKey(Access Token)，点"校验 Token"。保存后 token 落盘在 `DATA_DIR/settings.json`。
+2. **添加仓库**：搜索 GitLab 项目 → 选中 → 添加 → 自动 Clone。
+3. **操作列**：Clone / 分析(跑 codegraph init) / 状态 / 移除(删目录+注册)。
+
+## 关键运维点
+- **clone 基目录**（界面上填的"仓库克隆基目录"）应指向本地磁盘；索引放网络盘会退化。
+- **版本对齐**：GitLab 项目克隆的是你选的**默认分支**；若要分析部署版本，注册时改 gitUrl/branch 指向部署分支/tag。
+- **登录/鉴权**：默认仅本机。要团队访问：`HOST=0.0.0.0` + `ADMIN_TOKEN=...`，并建议前加 Nginx/TLS。
+- **token 安全**：`settings.json` 里是明文 GitLab token——`chmod 600` DATA_DIR。
+- **代码库形态**：多独立仓库默认**每个 index 独立**（不跨仓）；跨仓调用链需 GitNexus groups 或 monorepo。
+
+## 本机已验证（Windows 开发机）
+- 设置持久化(settings.json) / 仓库注册表(repos.json) / GitLab 校验与搜索端点
+- clone → (codegraph 真实索引 `codegraph.db`) → status→indexed → remove(删目录+清注册) ✅
+- GitLab 实网 clone/搜索需你填真实 GitLab URL + AppKey 验证（本机已用本地 git 源测通 clone 机制）。

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Zhao-T-X
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.en.md

@@ -0,0 +1,220 @@
+<div align="center">
+
+# CodeGraph Manager
+
+**Turn your entire codebase into a knowledge graph your AI can read.**
+
+Manage repositories from GitLab / Gitee / GitHub in one place, build a code knowledge graph with [CodeGraph](https://github.com/colbymchenry/codegraph), and let AI agents like Cursor or Claude query your code directly over **MCP (Model Context Protocol)**.
+
+[![Node](https://img.shields.io/badge/node-%E2%89%A522.5-339933?logo=node.js&logoColor=white)](https://nodejs.org)
+[![Zero Dependencies](https://img.shields.io/badge/dependencies-0-brightgreen)](#-dependencies)
+[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](#-license)
+[![MCP](https://img.shields.io/badge/MCP-Streamable%20HTTP-8A2BE2)](#-mcp-integration)
+
+<a href="README.md">🇨🇳 中文</a> · 🇬🇧 English
+
+</div>
+
+---
+
+Zero-dependency Node backend + single-file vanilla-JS frontend, **one command to start**: no database install, no build step, no Docker.
+The whole pipeline — clone → index → AI retrieval — runs automatically. Tokens are encrypted at rest; all data lives in one directory.
+
+## ✨ Features
+
+**Repository management**
+- Multi-provider — GitLab / Gitee / GitHub with multiple instances each; one cross-source query returns everything
+- Full lifecycle — one-click `clone → analyze → sync → remove`; shallow clone is ~10x faster
+- Local repos — register an already-cloned directory directly (auto-detects Git remote)
+- Branch worktrees — lazily spin up an isolated worktree per branch with its own index, so AI can query any branch; the main index stays clean automatically
+- Spaces — tag repos into groups and filter the UI by space
+  - Create: `All spaces → New Space` (top right); assign: `+ Spaces` on a repository row
+- Scheduled freshness — configurable auto `git pull + sync`; a failed pull is marked `pull_failed` instead of pretending the index is fresh
+
+**AI retrieval (MCP)**
+- 4 MCP tools (Streamable HTTP / JSON-RPC 2.0); cross-repo aggregated search — concurrent queries over all indexed repos, ranked hits with per-repo caps so your context window doesn't explode
+- Querying a branch with no index yet? The server builds one in the background and returns "retry shortly"
+
+**Security**
+- Route-level auth — `/api/*` and `/mcp*` guarded by `ADMIN_TOKEN` / `MCP_TOKEN`, constant-time comparison
+- Role-based access tokens — Settings → Access tokens creates `web` / `mcp` tokens; web tokens only see/operate repositories in their spaces, mcp tokens only search their spaces, admin is unrestricted
+- Loopback exemption — local access allowed by default (with same-origin checks so web pages can't hit your localhost); fail-closed when exposed: refuses to start without a token
+- Auto-generated 192-bit token on first start, persisted to `auth.json` — safe to expose without any manual setup
+- Token protection, three layers — AES-256-GCM at rest, masked in API responses (dots + last 4), masked PUT values never overwrite real tokens
+- 1 MB body limit (413), cross-origin requests always 401, `X-Forwarded-For` only trusted from configured proxies
+
+**Engineering**
+- SQLite storage (`node:sqlite`, zero npm dependencies) — transactional atomic writes; legacy JSON auto-migrates on first start
+- Three-tier concurrency control — global index queue + per-repo lifecycle mutex + per-file write serialization
+- Restart self-healing — interrupted in-flight states reset automatically; `CODEGRAPH_BIN` auto-detected (no manual config on Windows)
+- SSE live status push with 30s polling fallback; `BASE_PATH` for reverse-proxy sub-path deployments
+- Built-in regression suite `node verify-mcp.mjs` (49 assertions: protocol / auth / masking / concurrency / migration)
+
+## 📸 Screenshots
+
+| Overview | Repositories |
+|---|---|
+| ![Overview](public/img/index.png) | ![Repositories](public/img/repo-show.png) |
+
+| Add provider | Settings |
+|---|---|
+| ![Add provider](public/img/add-provider.png) | ![Settings](public/img/setting.png) |
+
+> Screenshots use sample data (Acme), not real repositories.
+
+## 🚀 Quick Start
+
+**One-click install** (installs anything missing: Node → git → CodeGraph → cgm, skips what's already there):
+
+```bash
+bash install.sh --port 8801          # Linux / macOS
+.\install.cmd --port 8801            # Windows (or double-click install.cmd)
+```
+
+**Manual install**:
+
+```bash
+npm i -g @colbymchenry/codegraph     # the only external dependency
+npm i -g @kennyzhao/cgm              # or: npm i -g . inside this repo
+cgm                                  # start from any directory
+```
+
+Open **http://127.0.0.1:8801** → Settings → add a provider → Add Selected → Clone & Analyze. Done.
+
+> CLI precedence: flags > environment variables > defaults. `cgm --port 9000 --data /srv/cgm-data`
+
+## 🔌 MCP Integration
+
+MCP endpoint: `http://127.0.0.1:8801/mcp` (Streamable HTTP / JSON-RPC 2.0)
+
+> UI: **Settings → MCP access** copies the endpoint and a ready `mcpServers` config; loopback gets a header-free version, non-loopback includes a Bearer placeholder.
+
+**Cursor / Claude Desktop / Cline** (standard `mcpServers` format, also shipped as `mcp-config.json`):
+
+```json
+{
+  "mcpServers": {
+    "cgm": {
+      "url": "http://127.0.0.1:8801/mcp",
+      "headers": { "Authorization": "Bearer <your-token>" }
+    }
+  }
+}
+```
+
+> Local access is token-free by default, so `headers` is optional. Where does the token come from: the first-start log, or `<DATA_DIR>/auth.json` (`adminToken`); you can also set `ADMIN_TOKEN` explicitly. URL-only clients can fall back to `?token=<token>`.
+
+### Tools
+
+| Tool | Description |
+|---|---|
+| `query_repository(name)` | Look up a repo by name: local path / status / provider |
+| `list_repositories(status?)` | List registered repos, filterable by status |
+| `search_repositories(query)` | Fuzzy repo-name search |
+| `search_code(query, repo?, branch?, maxFiles?)` | **The core search**: queries the CodeGraph knowledge graph for symbols / files / call relationships. Omit `repo` to aggregate across all indexed repos |
+
+Branch-scoped query example:
+
+```json
+{"jsonrpc":"2.0","id":1,"method":"tools/call",
+ "params":{"name":"search_code","arguments":{"query":"AuthService loginUser","repo":"tineco-nmp","branch":"dev_ibu","maxFiles":12}}}
+```
+
+## ⚙️ Configuration
+
+| Variable | Default | Description |
+|---|---|---|
+| `PORT` / `HOST` | `8801` / `127.0.0.1` | Listen address; non-loopback `HOST` requires a token (refuses to start otherwise) |
+| `DATA_DIR` | `<cwd>/data` | Data directory (`cgm.db`; cloned repos default to `<DATA_DIR>/repos`) |
+| `ADMIN_TOKEN` | auto-generated | Token for `/api/*`; on first start a random one is generated into `auth.json` |
+| `MCP_TOKEN` | falls back to `ADMIN_TOKEN` | Token for `/mcp*` (one variable is enough for personal use) |
+| `LOCAL_NO_AUTH` | `1` | Loopback auth exemption; set `0` to require auth locally too |
+| `BASE_PATH` | empty | Reverse-proxy sub-path (e.g. `/cgm` → endpoints under `/cgm/mcp`) |
+| `MAX_BODY_BYTES` | `1048576` | Request body limit, over-limit returns 413 |
+| `TRUSTED_PROXIES` | empty | Comma-separated trusted proxy IPs; `X-Forwarded-For` only honored from these |
+| `CODEGRAPH_BIN` | auto-detected | CodeGraph executable (PATH probe → npm global shim → explicit) |
+| `SYNC_HOURS` | `6` | Scheduled sync interval in hours, `0` disables; also configurable in Settings |
+| `QUEUE_CONCURRENCY` | `2` | Index queue concurrency |
+| `ENCRYPTION_KEY` | auto-generated `.key` | 64-char hex AES-256-GCM key |
+
+## 🔒 Security Model
+
+| Scenario | Behavior |
+|---|---|
+| Local 127.0.0.1 access | Token-free by default (dev-friendly); cross-origin web requests still get 401 |
+| LAN / remote access | Token required (Bearer header / `?token=` / Cookie) |
+| `HOST=0.0.0.0` with no token | Starts with an auto-generated random token; the log tells you where it is |
+| Token exposure surface | Encrypted at rest + masked via API + printed to log once, on first start only |
+
+`data/` is excluded by `.gitignore` — real tokens never enter version control. For public exposure, put Nginx + HTTPS in front (see [DEPLOY-Linux.md](DEPLOY-Linux.md)).
+
+## 🔌 API Reference
+
+| Endpoint | Methods | Description |
+|---|---|---|
+| `/healthz` | GET | Liveness probe (no auth) |
+| `/api/settings` | GET/PUT | Global settings (tokens masked in responses) |
+| `/api/providers[/...]` | GET/POST/PUT/DELETE | Provider CRUD + connection test + cross-source project search |
+| `/api/repos[/local]` | GET/POST | Registry / add a local repo |
+| `/api/repos/:id/{clone,analyze,status,remove,sync}` | POST | Per-repo ops (async; same-repo ops are automatically serialized) |
+| `/api/repos/:id/worktree/:branch` | POST/DELETE | Create / remove a branch worktree |
+| `/api/spaces[/...]` | GET/POST/PUT/DELETE | Space management / repo binding |
+| `/api/tokens[/...]` | GET/POST/DELETE | Access-token management (admin): roles + space scopes |
+| `/api/browse?path=` | GET | Server-side directory browser (for adding local repos) |
+| `/mcp` · `/mcp/message` | POST/GET | MCP endpoint (Streamable HTTP + SSE) |
+
+## ❓ FAQ
+
+<details>
+<summary><b>codegraph ENOENT on startup?</b></summary>
+
+On Windows the globally installed codegraph is a bash shim that can't be spawned directly. The service auto-detects it and rewrites it as `["node", "<shim>"]` — no manual `CODEGRAPH_BIN` needed on recent versions.
+</details>
+
+<details>
+<summary><b>Frontend keeps returning 401 after I set ADMIN_TOKEN?</b></summary>
+
+The page pops up a token prompt — paste the token there (stored in localStorage). Or clear the `cgm_token` localStorage key and re-enter.
+</details>
+
+<details>
+<summary><b>Will I lose data?</b></summary>
+
+Everything lives in one `<DATA_DIR>` (SQLite + keys + auth.json); backing up = copying the directory. Legacy JSON files auto-migrate on first start and are kept as `*.json.migrated-*` — delete `cgm.db*`, rename them back, and you've rolled back.
+</details>
+
+<details>
+<summary><b>Search results feel stale?</b></summary>
+
+Check the status column: `pull_failed` means the scheduled pull failed (retried next round). You can also hit Sync manually. Indexes are updated incrementally via CodeGraph sync.
+</details>
+
+## 🛠 Development
+
+```bash
+git clone https://github.com/Zhao-T-X/CGM.git && cd CGM
+node server.mjs                # dev server (127.0.0.1:8801)
+node verify-mcp.mjs            # regression suite: 49 assertions (protocol/auth/security/concurrency/migration)
+```
+
+```
+cgm/
+├── cli.mjs            CLI entry (the cgm command)
+├── server.mjs         HTTP backend (route auth, providers/repos/spaces, SQLite persistence)
+├── mcp.mjs            MCP module (4 tools + CodeGraph stdio gateway client)
+├── verify-mcp.mjs     Regression suite (49 assertions, isolated temp instances)
+├── public/index.html  Single-file frontend (Vercel-style dark UI)
+└── install.sh/.cmd    One-click installers
+```
+
+## 🚢 Release (maintainers)
+
+Pushing a `v*` tag triggers GitHub Actions to publish to npm (tag/version check → `npm pack --dry-run` → `npm publish --provenance`; requires the `NPM_TOKEN` secret).
+
+```bash
+npm version patch && git push --follow-tags
+```
+
+## 📄 License
+
+MIT

package/README.md

@@ -1,3 +1,221 @@
-# Temporary Holding Version
+<div align="center">
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+# CodeGraph Manager
+
+**把整个代码库变成 AI 能读懂的知识图谱。**
+
+统一管理 GitLab / Gitee / GitHub 仓库，自动用 [CodeGraph](https://github.com/colbymchenry/codegraph) 构建代码知识图谱，
+通过 **MCP（Model Context Protocol）** 让 Cursor、Claude 等 AI 代理直接检索你的代码。
+
+[![Node](https://img.shields.io/badge/node-%E2%89%A522.5-339933?logo=node.js&logoColor=white)](https://nodejs.org)
+[![Zero Dependencies](https://img.shields.io/badge/dependencies-0-brightgreen)](#-依赖)
+[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](#-license)
+[![MCP](https://img.shields.io/badge/MCP-Streamable%20HTTP-8A2BE2)](#-mcp-接入)
+
+🇨🇳 中文 · <a href="README.en.md">🇬🇧 English</a>
+
+</div>
+
+---
+
+零依赖 Node 后端 + 单文件原生 JS 前端，**一条命令启动**：无需数据库安装、无需构建步骤、无需 Docker。
+仓库 clone → 索引 → AI 检索全流程自动化，Token 加密落盘，数据一个目录全带走。
+
+## ✨ 功能
+
+**仓库管理**
+- 多提供商统一管理 —— GitLab / Gitee / GitHub 多实例并存，跨源搜索一次出结果
+- 全生命周期 —— `clone → analyze → sync → remove` 一键流转，浅克隆提速 10 倍级
+- 本地仓库直纳 —— 已克隆目录直接注册，自动识别 Git 远程
+- 多分支 worktree —— 按分支懒加载切出独立 worktree 并各建索引，AI 可检索任意分支；主索引自动豁免不污染
+- 空间分组 —— 仓库打标签分组，界面按空间筛选
+  - 新建空间：右上角 `All spaces → New Space`；分配仓库：仓库行 `+ Spaces`
+- 定时保新鲜 —— 可配置周期自动 `git pull + sync`；拉取失败明确标记 `pull_failed`，不假装索引是最新的
+
+**AI 检索（MCP）**
+- 4 个 MCP 工具（Streamable HTTP / JSON-RPC 2.0），跨仓聚合检索：并发查所有已索引仓库，命中排序 + 每仓收敛，上下文不爆炸
+- 首次检索未建索引的分支自动后台建索引，完成后即可用
+
+**安全**
+- 路由级鉴权 —— `/api/*` 与 `/mcp*` 分别持 `ADMIN_TOKEN` / `MCP_TOKEN`，`timingSafeEqual` 恒时比较
+- 角色化访问令牌 —— Settings → Access tokens 创建 `web` / `mcp` token；web 只能查看/操作授权空间内的仓库，mcp 只能检索授权空间，admin 无限制
+- 回环免鉴权 —— 本机访问默认放行（同源校验防网页打本地），对外开放时 fail-closed：无 token 拒绝启动
+- 首启自动生成随机令牌（192bit）持久化到 `auth.json`，不用手动配也能安全对外开放
+- Token 三重防护 —— 落盘 AES-256-GCM 加密、API 返回脱敏（掩码+末4位）、PUT 掩码不覆盖真值
+- 请求体 1MB 上限（413）、跨源 Origin 一律 401、`X-Forwarded-For` 仅信可信代理
+
+**工程化**
+- SQLite 存储（`node:sqlite`，零 npm 依赖）—— 事务原子写，旧 JSON 首启自动迁移
+- 三级并发治理 —— 全局索引队列限流 + 单仓生命周期互斥 + 每文件写串行，多仓并发不互踩
+- 重启自愈 —— 中断的运行中状态自动重置；`CODEGRAPH_BIN` 自动探测，Windows 无需手配
+- SSE 实时推送状态，30s 兜底轮询；`BASE_PATH` 支持反代子路径部署
+- 内置回归脚本 `node verify-mcp.mjs`（49 项断言：协议合规 / 鉴权 / 脱敏 / 并发 / 迁移）
+
+## 📸 界面
+
+| 概览 | 仓库管理 |
+|---|---|
+| ![概览](public/img/index.png) | ![仓库管理](public/img/repo-show.png) |
+
+| 添加提供商 | 设置 |
+|---|---|
+| ![添加提供商](public/img/add-provider.png) | ![设置](public/img/setting.png) |
+
+> 截图使用示例数据（Acme），不代表真实仓库内容。
+
+## 🚀 快速开始
+
+**一键安装**（自动装齐 Node → git → CodeGraph → cgm，已装的自动跳过）：
+
+```bash
+bash install.sh --port 8801          # Linux / macOS
+.\install.cmd --port 8801            # Windows（或双击 install.cmd）
+```
+
+**手动安装**：
+
+```bash
+npm i -g @colbymchenry/codegraph     # 唯一外部依赖
+npm i -g @kennyzhao/cgm              # 或在本仓库根目录 npm i -g .
+cgm                                  # 任意目录一键启动
+```
+
+打开 **http://127.0.0.1:8801** → Settings 添加提供商 → Add Selected → Clone & Analyze，完成。
+
+> CLI 参数优先级：命令行 > 环境变量 > 默认值。`cgm --port 9000 --data /srv/cgm-data`
+
+## 🔌 MCP 接入
+
+MCP 端点：`http://127.0.0.1:8801/mcp`（Streamable HTTP / JSON-RPC 2.0）
+
+> UI 入口：**Settings → MCP access** 可直接复制 endpoint 与 `mcpServers` 客户端配置；本机生成无 header 版本，非 loopback 自动带 Bearer 占位。
+
+**Cursor / Claude Desktop / Cline**（`mcpServers` 标准格式，本仓库附带 `mcp-config.json`）：
+
+```json
+{
+  "mcpServers": {
+    "cgm": {
+      "url": "http://127.0.0.1:8801/mcp",
+      "headers": { "Authorization": "Bearer <你的令牌>" }
+    }
+  }
+}
+```
+
+> 本机访问默认免鉴权，`headers` 可省略。令牌从哪来：首次启动日志，或 `<DATA_DIR>/auth.json` 的 `adminToken`；也可用环境变量 `ADMIN_TOKEN` 显式指定。只能填 URL 的客户端可用 `?token=<令牌>` 兜底。
+
+### 工具列表
+
+| 工具 | 说明 |
+|---|---|
+| `query_repository(name)` | 按名查仓库：本地路径 / 状态 / 提供商 |
+| `list_repositories(status?)` | 列出注册仓库，可按状态过滤 |
+| `search_repositories(query)` | 模糊搜索仓库名 |
+| `search_code(query, repo?, branch?, maxFiles?)` | **核心检索**：查 CodeGraph 知识图谱，返回符号 / 文件 / 调用关系。不传 `repo` 则跨所有已索引仓库聚合 |
+
+按分支检索示例：
+
+```json
+{"jsonrpc":"2.0","id":1,"method":"tools/call",
+ "params":{"name":"search_code","arguments":{"query":"AuthService loginUser","repo":"tineco-nmp","branch":"dev_ibu","maxFiles":12}}}
+```
+
+## ⚙️ 配置
+
+| 变量 | 默认 | 说明 |
+|---|---|---|
+| `PORT` / `HOST` | `8801` / `127.0.0.1` | 监听地址；`HOST` 非回环时必须配 token（无则拒绝启动） |
+| `DATA_DIR` | `<cwd>/data` | 数据目录（`cgm.db` + 克隆仓库默认存 `<DATA_DIR>/repos`） |
+| `ADMIN_TOKEN` | 自动生成 | `/api/*` 令牌；未设置时首启生成随机值写入 `auth.json` |
+| `MCP_TOKEN` | 回落 `ADMIN_TOKEN` | `/mcp*` 令牌（自用只配一个变量即可） |
+| `LOCAL_NO_AUTH` | `1` | 回环免鉴权开关；设 `0` 本机也强制鉴权 |
+| `BASE_PATH` | 空 | 反代子路径（如设 `/cgm` 后经 `/cgm/mcp` 访问） |
+| `MAX_BODY_BYTES` | `1048576` | 请求体上限，超限 413 |
+| `TRUSTED_PROXIES` | 空 | 逗号分隔可信代理 IP，仅对可信代理采信 `X-Forwarded-For` |
+| `CODEGRAPH_BIN` | 自动探测 | CodeGraph 可执行（PATH 探测 → npm 全局 shim → 显式指定） |
+| `SYNC_HOURS` | `6` | 定时同步周期（小时），`0` 关闭；UI Settings 可覆盖 |
+| `QUEUE_CONCURRENCY` | `2` | 索引队列并发数 |
+| `ENCRYPTION_KEY` | 自动生成 `.key` | 64 位 hex，AES-256-GCM 密钥 |
+
+## 🔒 安全模型
+
+| 场景 | 行为 |
+|---|---|
+| 本机 127.0.0.1 访问 | 默认免鉴权（开发/自用友好），跨源网页请求仍被 401 拦截 |
+| 局域网 / 远程访问 | 必须持令牌（Bearer 头 / `?token=` / Cookie 任一） |
+| `HOST=0.0.0.0` 且无令牌 | 启动时用自动生成的随机令牌兜底，日志打印令牌位置 |
+| 令牌泄露面 | 落盘加密 + API 脱敏 + 首启仅日志打印一次 |
+
+`data/` 已被 `.gitignore` 排除，真实 token 永不入库。对外开放建议叠加 Nginx 反代 + HTTPS（见 [DEPLOY-Linux.md](DEPLOY-Linux.md)）。
+
+## 🔌 API 参考
+
+| 端点 | 方法 | 说明 |
+|---|---|---|
+| `/healthz` | GET | 存活探针（无鉴权） |
+| `/api/settings` | GET/PUT | 全局配置（返回值 token 已脱敏） |
+| `/api/providers[/...]` | GET/POST/PUT/DELETE | 提供商 CRUD + 连接测试 + 跨源项目搜索 |
+| `/api/repos[/local]` | GET/POST | 仓库注册表 / 添加本地仓库 |
+| `/api/repos/:id/{clone,analyze,status,remove,sync}` | POST | 单仓操作（异步执行，同仓操作自动排队互斥） |
+| `/api/repos/:id/worktree/:branch` | POST/DELETE | 分支 worktree 创建 / 删除 |
+| `/api/spaces[/...]` | GET/POST/PUT/DELETE | 空间分组管理 / 仓库绑定 |
+| `/api/tokens[/...]` | GET/POST/DELETE | 访问令牌管理（admin）：角色 + 空间范围 |
+| `/api/browse?path=` | GET | 服务端目录浏览（添加本地仓库用） |
+| `/mcp` · `/mcp/message` | POST/GET | MCP 端点（Streamable HTTP + SSE） |
+
+## ❓ 常见问题
+
+<details>
+<summary><b>启动报 codegraph ENOENT？</b></summary>
+
+Windows 全局安装的 codegraph 是 bash shim，PATH 直接 spawn 不通。本服务会自动探测并转成 `["node", "<shim>"]` 形式；老版本升级后无需再手配 `CODEGRAPH_BIN`。
+</details>
+
+<details>
+<summary><b>配了 ADMIN_TOKEN 后前端一直 401？</b></summary>
+
+页面会弹出令牌输入框，粘贴令牌即可（存浏览器 localStorage）。或清除 localStorage 里的 `cgm_token` 重新输入。
+</details>
+
+<details>
+<summary><b>数据会丢吗？</b></summary>
+
+所有数据在 `<DATA_DIR>` 一个目录（SQLite + 密钥 + auth.json），备份 = 拷贝目录。旧版 JSON 文件首启自动迁移，原文件改名 `*.json.migrated-*` 保留，删掉 `cgm.db*` 改回原名即可回退。
+</details>
+
+<details>
+<summary><b>检索结果过时？</b></summary>
+
+看仓库状态列：`pull_failed` 表示定时同步拉取失败（下轮自动重试）；也可手动点 Sync。索引基于 CodeGraph 增量 sync。
+</details>
+
+## 🛠 开发
+
+```bash
+git clone https://github.com/Zhao-T-X/CGM.git && cd CGM
+node server.mjs                # 开发启动（127.0.0.1:8801）
+node verify-mcp.mjs            # 回归测试：49 项断言（协议/鉴权/安全/并发/迁移）
+```
+
+```
+cgm/
+├── cli.mjs            CLI 入口（cgm 命令）
+├── server.mjs         HTTP 后端（路由鉴权、提供商/仓库/空间、SQLite 持久化）
+├── mcp.mjs            MCP 模块（4 工具 + CodeGraph stdio 网关客户端）
+├── verify-mcp.mjs     回归脚本（49 项断言，临时实例隔离运行）
+├── public/index.html  前端单文件（Vercel 风深色 UI）
+└── install.sh/.cmd    一键安装脚本
+```
+
+## 🚢 发布（维护者）
+
+推送 `v*` tag 触发 GitHub Actions 自动发 npm（tag 与版本校验 → `npm pack --dry-run` → `npm publish --provenance`，需配置 `NPM_TOKEN`）。
+
+```bash
+npm version patch && git push --follow-tags
+```
+
+## 📄 License
+
+MIT

package/cli.mjs

@@ -0,0 +1,68 @@
+#!/usr/bin/env node
+// CodeGraph Manager CLI —— 一键启动
+//
+// 安装全局命令:  npm i -g .   （项目根执行一次）
+// 使用:          cgm [选项]          任意目录一键启动服务
+// 不装全局:      node cli.mjs [选项] 效果相同
+//
+// 选项（优先级：命令行参数 > 环境变量 > 默认值）:
+//   --port <n>          监听端口       默认 8801
+//   --host <addr>       监听地址       默认 127.0.0.1（对外开放 0.0.0.0 并配 ADMIN_TOKEN）
+//   --data <dir>        数据目录       默认 ./data
+//   --codegraph <bin>   codegraph 调用方式   默认自动探测（PATH 里的 codegraph → npm 全局 shim）
+//   -v / --version      版本
+//   -h / --help         帮助
+import { createRequire } from 'node:module';
+
+const require = createRequire(import.meta.url);
+const { version } = require('./package.json');
+
+const HELP = `CodeGraph Manager v${version} —— 多 Git 平台仓库索引管理 + MCP 代码检索
+
+用法:
+  cgm [选项]                启动服务（前台运行，Ctrl+C 退出）
+  cgm -v | --version        显示版本
+  cgm -h | --help           显示本帮助
+
+选项（优先级：命令行参数 > 环境变量 > 默认值）:
+  --port <n>          监听端口            默认 8801
+  --host <addr>       监听地址            默认 127.0.0.1
+  --data <dir>        数据目录            默认 ./data（settings/repos/克隆仓库都在这，备份=拷目录）
+  --codegraph <bin>   codegraph 调用方式  默认自动探测，无需配置
+
+示例:
+  cgm                                  # 全默认：http://127.0.0.1:8801
+  cgm --port 9000 --data /srv/cgm-data # 自定义端口与数据目录
+  HOST=0.0.0.0 ADMIN_TOKEN=xxx cgm     # 对外开放（env 方式）
+  界面 http://127.0.0.1:<port>  ·  MCP 端点 /mcp  ·  探活 /healthz`;
+
+function fail(msg) { console.error(`cgm: ${msg}（--help 查看用法）`); process.exit(1); }
+
+const opts = {};
+const argv = process.argv.slice(2);
+for (let i = 0; i < argv.length; i++) {
+  const a = argv[i];
+  switch (a) {
+    case '-h': case '--help': console.log(HELP); process.exit(0);
+    case '-v': case '--version': console.log(version); process.exit(0);
+    case '--port': opts.port = argv[++i]; break;
+    case '--host': opts.host = argv[++i]; break;
+    case '--data': opts.data = argv[++i]; break;
+    case '--codegraph': opts.codegraph = argv[++i]; break;
+    case 'start': break; // 兼容 `cgm start` 写法
+    default: fail(`未知参数: ${a}`);
+  }
+}
+
+// 参数映射为环境变量（server.mjs 顶层读取），显式参数覆盖 env
+if (opts.port !== undefined) {
+  const p = Number.parseInt(opts.port, 10);
+  if (!Number.isInteger(p) || p <= 0 || p > 65535) fail(`非法端口: ${opts.port}`);
+  process.env.PORT = String(p);
+}
+if (opts.host !== undefined) process.env.HOST = opts.host;
+if (opts.data !== undefined) process.env.DATA_DIR = opts.data;
+if (opts.codegraph !== undefined) process.env.CODEGRAPH_BIN = opts.codegraph;
+
+// env 已就位，动态加载服务入口（顶层读取上述变量完成初始化）
+await import('./server.mjs');

package/install.cmd

@@ -0,0 +1,5 @@
+@echo off
+rem CodeGraph Manager 一键安装（Windows 双击入口）：Node -> git -> codegraph -> cgm -> 启动
+rem 参数透传给 cgm，例如: install.cmd --port 9000
+powershell -NoProfile -ExecutionPolicy Bypass -File "%~dp0install.ps1" %*
+pause

package/install.ps1

@@ -0,0 +1,55 @@
+# CodeGraph Manager 一键安装（Windows）
+# 自动安装缺失依赖：Node.js(>=18) → git → CodeGraph → cgm，然后启动服务
+# 用法: .\install.cmd [cgm 参数透传]   例: .\install.cmd --port 9000 --data E:\cgm-data
+# 也可: powershell -NoProfile -ExecutionPolicy Bypass -File install.ps1
+$ErrorActionPreference = 'Stop'
+$Repo = Split-Path -Parent $MyInvocation.MyCommand.Path
+
+function Say($m) { Write-Host "==> $m" -ForegroundColor Green }
+function Refresh-Path {
+  $env:Path = [Environment]::GetEnvironmentVariable('Path', 'Machine') + ';' +
+              [Environment]::GetEnvironmentVariable('Path', 'User')
+}
+function Get-NodeMajor {
+  try { return [int](((node -v) -replace '^v', '').Split('.')[0]) } catch { return 0 }
+}
+function Install-Winget([string]$Id) {
+  if (-not (Get-Command winget -ErrorAction SilentlyContinue)) {
+    Write-Error "未找到 winget，请手动安装后重试（Node: https://nodejs.org / git: https://git-scm.com）"
+  }
+  winget install -e --id $Id --accept-source-agreements --accept-package-agreements
+  Refresh-Path
+}
+
+# ---------- 1) Node.js >= 18 ----------
+if ((Get-NodeMajor) -ge 18) {
+  Say "Node $(node -v) 已就绪"
+} else {
+  Say "安装 Node.js 22 LTS ..."
+  Install-Winget 'OpenJS.NodeJS.LTS'
+  if ((Get-NodeMajor) -lt 18) { Write-Error "Node 安装后仍不可用，请重开终端再运行本脚本" }
+}
+
+# ---------- 2) git（服务端 clone 业务仓库依赖） ----------
+if (Get-Command git -ErrorAction SilentlyContinue) {
+  Say "git 已就绪"
+} else {
+  Say "安装 git ..."
+  Install-Winget 'Git.Git'
+}
+
+# ---------- 3) CodeGraph ----------
+if (Get-Command codegraph -ErrorAction SilentlyContinue) {
+  Say "codegraph 已就绪"
+} else {
+  Say "安装 CodeGraph ..."
+  npm i -g @colbymchenry/codegraph
+}
+
+# ---------- 4) cgm（本仓库 CLI，link 到全局） ----------
+Say "安装 cgm（npm i -g $Repo）..."
+npm i -g $Repo
+
+# ---------- 5) 启动（参数透传） ----------
+Say "启动 CodeGraph Manager ...（Ctrl+C 退出；参数透传给 cgm）"
+cgm @args