diff --git a/.codegraph/.gitignore b/.codegraph/.gitignore
new file mode 100644
index 0000000..d20c0fe
--- /dev/null
+++ b/.codegraph/.gitignore
@@ -0,0 +1,5 @@
+# CodeGraph data files — local to each machine, not for committing.
+# Ignore everything in .codegraph/ except this file itself, so transient
+# files (the database, daemon.pid, sockets, logs) never show up in git.
+*
+!.gitignore
diff --git a/AGENTS.md b/AGENTS.md
index cdfde71..123b64a 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -1,6 +1,6 @@
 # 仓库说明
 
-本仓库用于维护可通过一次 `pi install` 部署的个人 Pi 扩展组合包。根 `package.json` 是唯一安装入口；依赖、默认行为和必要配置必须由组合包自身声明或部署，不把安装后的手工配置作为默认流程。每个自维护扩展使用独立的顶层目录，扩展源码、测试和说明应保留在各自目录内。
+本仓库用于维护可通过一次 `pi install` 部署的个人 Pi 扩展组合包。根 `package.json` 是唯一的组合包安装入口；根 `install.sh` 和 `uninstall.sh` 只是对 `pi install` / `pi remove` 的便捷包装，不形成第二套部署机制。依赖、默认行为和必要配置必须由组合包自身声明或部署，不把安装后的手工配置作为默认流程。每个自维护扩展使用独立的顶层目录，扩展源码、测试和说明应保留在各自目录内。
 
 ## 当前扩展
 
@@ -19,6 +19,8 @@
 - `@ogulcancelik/pi-auto-permissions@0.1.3`：根据当前对话复核配置命中的 Bash 命令，不是全工具审批层。
 - `@ogulcancelik/pi-codex-compaction@0.1.3`：为 `openai-codex` 提供原生远程 compaction，默认阈值为 90%。
 - 根包还固定安装 `pi-context-view`、`@firstpick/pi-extension-codex-fast-mode` 和 `@gotgenes/pi-permission-system`。
+- `install.sh`：先安装根组合包，再交互检查 CodeGraph、Kotlin LSP、Java 21+ 和 JDT LS；缺失依赖只在用户明确选择 `Y` 后安装。
+- `uninstall.sh`：只移除根组合包，不卸载可能被其他项目共享的 CodeGraph、Kotlin LSP、JDT LS 或 Java。
 
 ## 当前职责与默认行为
 
@@ -28,7 +30,7 @@
 - `readCompaction.enabled`、`sourceCodeFilteringEnabled` 和 `smartTruncate.enabled` 当前均默认 `false`，源码读取保持原样。未经用户明确决定，不因节省上下文而改变这些默认值。
 - 若以后开启 read 压缩，优先考虑 `readCompaction + smartTruncate`，源码过滤仍独立评估；必须保留精确 `offset/limit` 读取、短文件和行锚点的完整性。
 - Context Mode 负责避免批量读取、命令研究和网页原始内容直接撑大上下文；FFF 仍负责精确字面搜索，RTK 仍处理未走 Context Mode 的普通输出。
-- CodeGraph 只配置 Pi 到外部 `codegraph` 命令的 MCP 连接。组合包不安装 CodeGraph，不执行 `codegraph init`，不创建或管理 `.codegraph/`，也不改动索引、更新或遥测设置。
+- CodeGraph 扩展只配置 Pi 到外部 `codegraph` 命令的 MCP 连接。根包安装本身不安装 CodeGraph；便捷脚本仅在组合包安装完成且用户明确选择 `Y` 后调用官方安装器。仓库不执行 `codegraph init`，不创建或管理 `.codegraph/`，也不改动索引、更新或遥测设置。
 - CodeGraph MCP 使用 `keep-alive` 并只直接暴露 `codegraph_explore`；命令缺失、项目未初始化或连接失败时不得阻止其他扩展加载。
 - `pi-context-view` 只观察上下文占用，不参与压缩策略。
 - Codex fast mode 只为符合条件的 `openai-codex-responses` 请求设置 priority service tier，由 `/fast-mode` 在会话内控制。
@@ -37,8 +39,11 @@
 - 两个权限扩展是彼此独立的 `tool_call` gate。若同一 Bash 命令同时命中 Auto Permissions 规则和 `pi-permission-system` 的 `ask`，会依次经过两层审批，而不是把旧系统的请求转交给 guardian；配置时不得为同一 Bash 类别重复设置审批。
 - 当前只把 Git 非只读操作和包管理类 Bash 命令交给 `pi-auto-permissions` 根据用户上下文复核。低风险操作可自动允许；中风险操作仅在用户明确授权目标与约束时自动允许；高风险操作即使已有概括授权也必须回到用户确认。文件/系统/网络高风险操作继续由现有解析能力更强的 `pi-permission-system` 处理。
 - 将 Auto Permissions 规则配置为 `.*` 最多只能复核所有 Bash 命令，不能覆盖其他工具，并会为普通 Bash 调用增加额外模型请求、延迟和成本。若未来目标是让现有所有 `ask` 先经模型裁决，必须另行实现 `pi-permission-system` authorizer 集成，不能仅靠该 npm 包配置实现。
-- `pi-lsp` 使用组合包部署的 `kotlin-lsp --stdio` 与 `jdtls` 配置，但不安装这两个系统可执行文件。
+- `pi-lsp` 使用组合包部署的 `kotlin-lsp --stdio` 与 `jdtls` 配置，但根包安装本身不安装这两个系统可执行文件；便捷脚本可在用户逐项明确确认后通过 Homebrew 安装 Kotlin LSP、Java 21 和 JDT LS。
 - Codex 远程压缩只对 `openai-codex` 生效，默认在 turn boundary 达到 90% 时触发；Hermes Memory 默认使用 policy-only 模式。
+- `install.sh` 默认从 `git:git@bitbucket.org:siakitem/my-pi.git` 安装，并允许用 `PI_PACKAGE_SOURCE` 覆盖来源；组合包安装失败时立即停止，机器级依赖安装失败时继续检查其余依赖并最终返回非零状态。
+- CodeGraph 的可选安装使用官方远程安装脚本；Kotlin LSP、Java 21 和 JDT LS 的可选安装使用 Homebrew。没有 Homebrew 时保留已经完成的组合包安装并报告依赖安装失败。
+- `install.sh` 不检查默认不需要的 `rtk` CLI；`uninstall.sh` 使用同一个 `PI_PACKAGE_SOURCE` 规则调用 `pi remove`，且不删除共享机器级工具。
 
 ## 修改边界
 
@@ -49,7 +54,9 @@
 - 需要原生构建的依赖只按锁定版本加入根 `allowScripts`；当前仅允许 Hermes Memory 所需的 `better-sqlite3`，不得批量批准其他 install scripts。
 - Pi 核心包只作为宿主 peer dependencies，不得在组合包内再安装或打包一套 Pi runtime；保留根 `.npmrc` 的 peer 安装策略。
 - 上游仅作为参考来源。同步上游改动时先核对本仓库已有修改，再按明确范围移植；不要直接覆盖本地实现。
-- 未经明确要求，不执行发布、提交、推送或安装到用户 Pi 运行目录等外部写操作。
+- `install.sh` 和 `uninstall.sh` 必须保持 POSIX `sh` 兼容和可执行权限，并包含在根 `package.json` 的 `files` 中；修改脚本行为时同步更新 README 和本文件。
+- 机器级依赖安装必须保持逐项询问且默认拒绝，不得在没有用户明确确认的情况下自动安装；卸载不得顺带删除共享机器级工具。
+- 未经明确要求，不执行发布、提交、推送、运行安装/卸载脚本或安装到用户 Pi 运行目录等外部写操作。
 
 ## `pi-rtk-optimizer` 开发约定
 
@@ -65,6 +72,8 @@
 
 组合包依赖或加载入口变化时，至少验证根 `npm install` 幂等、锁文件有效，以及全部扩展可在隔离的临时 Pi agent 目录加载。权限配置变化时使用当前固定版本的 `pi-permission-system` schema 校验，并验证包装入口部署后的文件与仓库源配置一致。
 
+安装或卸载脚本变化时，至少运行 `sh -n install.sh`、`sh -n uninstall.sh` 和 ShellCheck，并核对脚本仍具有可执行权限、仍包含在根 `package.json` 的 `files` 中、README 描述与实际流程一致。涉及真实 `pi install`、`pi remove`、Homebrew 或远程 CodeGraph 安装器的端到端验证属于外部写操作，未经明确要求不得执行。
+
 在 `pi-rtk-optimizer/` 内按改动范围选择最小充分验证：
 
 - `npm run build`：TypeScript 转译检查。
diff --git a/README.md b/README.md
index 5dd799c..b9b98e8 100644
--- a/README.md
+++ b/README.md
@@ -14,14 +14,41 @@
 - `@ogulcancelik/pi-auto-permissions@0.1.3`：按当前对话自动复核受控 Bash 操作。
 - `@gotgenes/pi-permission-system@26.2.1`：负责工具、路径、MCP、硬拒绝和兜底权限基线。
 
-## 安装
+## 安装与卸载
 
-仓库推送后，通过 Git 源安装整个组合包：
+推荐从仓库检出目录运行安装脚本：
+
+```bash
+./install.sh
+```
+
+脚本会先执行：
 
 ```bash
 pi install git:git@bitbucket.org:siakitem/my-pi.git
 ```
 
+安装组合包成功后，脚本会检查 `codegraph`、`kotlin-lsp`、Java 21+ 和 `jdtls`。缺失的
+依赖会逐项显示 `[y/N]` 选项，仅在用户明确选择 `Y` 后安装。Kotlin、Java 和 JDT LS 的
+自动安装使用 Homebrew；如果机器没有 Homebrew，脚本会保留组合包安装结果并给出提示。
+`rtk` 只供默认关闭的命令改写使用，因此不会作为必装依赖检查。
+
+也可以绕过脚本，直接运行上面的 `pi install` 命令，此时机器级 CLI 不会被检查。
+
+卸载组合包：
+
+```bash
+./uninstall.sh
+```
+
+卸载脚本只调用 `pi remove`，不会删除 CodeGraph、Kotlin LSP、JDT LS 或 Java，因为这些
+机器级工具可能仍被其他项目使用。两个脚本都可通过 `PI_PACKAGE_SOURCE` 覆盖默认包源，
+例如在本地检出中测试：
+
+```bash
+PI_PACKAGE_SOURCE="$PWD" ./install.sh
+```
+
 根 `package.json` 使用精确版本，`package-lock.json` 固定完整依赖树。不要再用项目级
 `.pi/settings.json` 重复安装这些扩展，否则同一扩展可能被加载两次。
 
diff --git a/install.sh b/install.sh
new file mode 100755
index 0000000..ece7905
--- /dev/null
+++ b/install.sh
@@ -0,0 +1,155 @@
+#!/bin/sh
+
+set -u
+
+PACKAGE_SOURCE=${PI_PACKAGE_SOURCE:-git:git@bitbucket.org:siakitem/my-pi.git}
+CODEGRAPH_INSTALL_URL=https://raw.githubusercontent.com/colbymchenry/codegraph/main/install.sh
+install_failed=0
+
+say() {
+	printf '%s\n' "$*"
+}
+
+warn() {
+	printf '警告: %s\n' "$*" >&2
+}
+
+ask_to_install() {
+	dependency=$1
+	printf '未检测到 %s。是否现在安装？[y/N] ' "$dependency"
+	if ! IFS= read -r answer; then
+		answer=n
+	fi
+	case $answer in
+		y|Y|yes|YES|Yes) return 0 ;;
+		*) return 1 ;;
+	esac
+}
+
+require_brew() {
+	if command -v brew >/dev/null 2>&1; then
+		return 0
+	fi
+
+	warn "自动安装该依赖需要 Homebrew，但当前 PATH 中没有 brew。"
+	warn "请先安装 Homebrew（https://brew.sh/），然后重新运行本脚本。"
+	return 1
+}
+
+record_install_failure() {
+	warn "$1 安装失败；其余依赖仍会继续检查。"
+	install_failed=1
+}
+
+java_major_version() {
+	java_version=$(java -version 2>&1 | awk -F '"' 'NR == 1 { print $2 }')
+	case $java_version in
+		1.*) java_version=${java_version#1.} ;;
+	esac
+	java_major=${java_version%%.*}
+	case $java_major in
+		''|*[!0-9]*) return 1 ;;
+		*) printf '%s\n' "$java_major" ;;
+	esac
+}
+
+install_codegraph() {
+	if ! command -v curl >/dev/null 2>&1; then
+		warn "安装 CodeGraph 需要 curl。"
+		return 1
+	fi
+	curl -fsSL "$CODEGRAPH_INSTALL_URL" | sh || return 1
+
+	# 官方安装器默认使用 ~/.local/bin；让本次检查立即看到新命令。
+	if [ -d "$HOME/.local/bin" ]; then
+		PATH="$HOME/.local/bin:$PATH"
+		export PATH
+	fi
+	command -v codegraph >/dev/null 2>&1
+}
+
+install_kotlin_lsp() {
+	require_brew || return 1
+	brew install JetBrains/utils/kotlin-lsp || return 1
+	command -v kotlin-lsp >/dev/null 2>&1
+}
+
+install_java_21() {
+	require_brew || return 1
+	brew install openjdk@21 || return 1
+	java_home=$(brew --prefix openjdk@21 2>/dev/null) || return 1
+	PATH="$java_home/bin:$PATH"
+	export PATH
+	installed_java_major=$(java_major_version || true)
+	if [ -z "$installed_java_major" ] || [ "$installed_java_major" -lt 21 ]; then
+		return 1
+	fi
+	say "已在本次安装流程中使用 $java_home/bin。若新终端仍找不到 Java，请把该目录加入 PATH。"
+}
+
+install_jdtls() {
+	require_brew || return 1
+	brew install jdtls || return 1
+	command -v jdtls >/dev/null 2>&1
+}
+
+if ! command -v pi >/dev/null 2>&1; then
+	warn "找不到 pi，无法安装组合包。请先安装 Pi 并确保 pi 位于 PATH。"
+	exit 127
+fi
+
+say "正在安装 Pi 组合包：$PACKAGE_SOURCE"
+if ! pi install "$PACKAGE_SOURCE"; then
+	warn "pi install 执行失败，已停止后续依赖检查。"
+	exit 1
+fi
+
+say "Pi 组合包安装完成，开始检查机器级 CLI 依赖。"
+
+if command -v codegraph >/dev/null 2>&1; then
+	say "✓ codegraph 已安装"
+elif ask_to_install "CodeGraph（提供 codegraph_explore）"; then
+	install_codegraph || record_install_failure "CodeGraph"
+else
+	say "- 已跳过 CodeGraph；codegraph_explore 将不可用。"
+fi
+
+if command -v kotlin-lsp >/dev/null 2>&1; then
+	say "✓ kotlin-lsp 已安装"
+elif ask_to_install "kotlin-lsp（Kotlin LSP）"; then
+	install_kotlin_lsp || record_install_failure "kotlin-lsp"
+else
+	say "- 已跳过 kotlin-lsp；Kotlin LSP 功能将不可用。"
+fi
+
+java_ok=0
+if command -v java >/dev/null 2>&1; then
+	java_major=$(java_major_version || true)
+	if [ -n "$java_major" ] && [ "$java_major" -ge 21 ]; then
+		java_ok=1
+		say "✓ Java $java_major 已安装（满足 Java 21+）"
+	fi
+fi
+
+if [ "$java_ok" -eq 0 ]; then
+	if ask_to_install "Java 21+（JDT LS 运行时）"; then
+		if install_java_21; then
+			java_ok=1
+		else
+			record_install_failure "Java 21+"
+		fi
+	else
+		say "- 已跳过 Java 21+；JDT LS 可能无法启动。"
+	fi
+fi
+
+if command -v jdtls >/dev/null 2>&1; then
+	say "✓ jdtls 已安装"
+elif ask_to_install "jdtls（Java LSP）"; then
+	install_jdtls || record_install_failure "jdtls"
+else
+	say "- 已跳过 jdtls；Java LSP 功能将不可用。"
+fi
+
+say "依赖检查完成。RTK 命令改写默认关闭，因此未检查可选的 rtk CLI。"
+exit "$install_failed"
diff --git a/package.json b/package.json
index 0e5212a..2825281 100644
--- a/package.json
+++ b/package.json
@@ -12,6 +12,8 @@
     "extensions",
     "pi-rtk-optimizer",
     "config",
+    "install.sh",
+    "uninstall.sh",
     "README.md",
     "AGENTS.md"
   ],
diff --git a/uninstall.sh b/uninstall.sh
new file mode 100755
index 0000000..3930ceb
--- /dev/null
+++ b/uninstall.sh
@@ -0,0 +1,14 @@
+#!/bin/sh
+
+set -u
+
+PACKAGE_SOURCE=${PI_PACKAGE_SOURCE:-git:git@bitbucket.org:siakitem/my-pi.git}
+
+if ! command -v pi >/dev/null 2>&1; then
+	printf '错误: 找不到 pi，无法卸载组合包。请确保 pi 位于 PATH。\n' >&2
+	exit 127
+fi
+
+printf '正在从 Pi 中移除组合包：%s\n' "$PACKAGE_SOURCE"
+pi remove "$PACKAGE_SOURCE"
+printf '%s\n' '组合包已移除。CodeGraph、Kotlin LSP、JDT LS 和 Java 均未卸载，因为它们可能仍被其他项目使用。'