install-maintenance-graft-rtk-ponytail-lite

提示词

# 已验证的安装和维护 — Graft + RTK + Ponytail lite

您正在当前仓库中安装、更新、修复或验证以下堆栈：

- Graft：代码理解、本地图谱和 LSP 增强。
- RTK：终端噪声减少。
- Ponytail：轻量级策略，兼容时原生集成。

从只读清单开始。然后询问下面缺失的问题。
在获得答案后，执行授权操作直至最终检查。

在确定客户端和范围之前，不要开始安装。
不要重复询问本对话中已给出的决定。

## 1. 清单，然后用户选择

### 不修改的清单

识别：

- 操作系统、架构、shell、环境：本地机器、WSL、SSH、容器；
- 仓库根目录、工作树、Git 状态和正在进行的 Git 操作；
- Git、Node、npm、RTK、Graft 及可用客户端的实际路径、版本和安装方式；
- 分别识别 Claude Code、Codex、Kimi、Cursor Agent CLI 和 Cursor IDE；
- 已存在的 Gemini、Copilot CLI 或其他客户端作为可选目标；
- 实际使用的配置目录、重定向变量，以及任何协调器如 AgentsRoom；
- 现有的用户、项目、插件和继承的钩子配置。

在将 `agent` 视为 Cursor 之前验证其身份。
存在的二进制文件并不证明认证、钩子功能或 MCP 加载。

在此清单过程中不要启动自动更新、连接或安装。
不要公开任何秘密值。

展示简短表格：
客户端 | 二进制/版本 | 有效配置 | 已知状态。

### 一次性询问的问题

仅询问缺失答案的问题：

1. 操作：
   - 安装缺失组件并保持兼容版本。
   - 更新堆栈至已验证的稳定版本。
   - 修复现有安装同时保持其版本。
   - 仅验证，不做修改。

2. 客户端：
   - 所有检测到的客户端。
   - 从实际检测列表中选择。
   - 也为某些缺失客户端准备配置。

3. 集成范围：
   - 共享项目：面向仓库的可移植配置。
   - 个人项目：针对该仓库激活，非版本控制的本地文件。
   - 全局用户：针对该用户的所有项目激活。
   - 混合：按客户端或组件区分选择。

如果范围为混合，仅询问必要的澄清。

对于更新，若未知版本约束，也需询问。
否则，建议明确的稳定版本。

不要安装或更新客户端应用程序本身：
操作涉及 Graft、RTK、Ponytail 及其必要依赖。
过时的客户端会报告所需版本和剩余操作。

### 使选择具体化

在写入前，展示计划结果：

组件/客户端 | 目标版本 | 范围 | 目标文件 | 共享效果 | 备用方案

特别说明：

- 用户级安装的可执行文件可服务多个仓库。
- 更新此可执行文件影响所有本地用户。
- 插件可能有全局缓存，但按项目激活。
- 每个项目的钩子仍可能使用共享状态。
- Graft 索引保持特定于仓库/工作树。
- 协调器提供的全局配置可隔离到项目：验证其实际范围，而非仅名称。

一旦获得选择，继续执行，不重复确认。
仅当限制需扩展范围或实质方案变更时，才请求新决定。

## 2. 执行规则

顺序：
清单 → 选择 → 备份 → RTK → Graft/LSP → Ponytail → 指令 → 验证 → 报告。

遵守仓库指令和管理策略。
若文件由 AgentsRoom 或其他协调器管理，使用其官方机制；不要直接修改其生成文件。

每次修改前：

- 验证 JSON/JSONC/TOML 配置的格式和结构；
- 备份受影响文件至仓库外，限制访问；
- 记录版本和回滚所需元素；
- 审查安装程序的模拟运行（dry-run），如存在。

无效文件绝不可被空配置替换。

合并配置时保留其他 MCP、钩子、权限、指令、注释（如可能）和状态行。
不要更改审批规则或信任指纹。

保留已有 Git 变更。禁止提交、推送、重置、清理、暂存或应用代码变更。
若存在未解决冲突或正在进行的 Git 操作，暂停仓库写入；继续独立诊断。

不要安装 Graphify、CodeGraph、Caveman 或 Headroom。
旧的冲突集成仅在精确识别、备份且在授权范围内时移除。
不要全局卸载其他地方使用的工具。

错误阻断其依赖步骤，不影响其他独立客户端。
不要声明步骤成功以绕过限制。

## 3. 能力和范围：配置前验证

查阅已安装版本的帮助及将使用的发布版本对应文档：

- https://github.com/rtk-ai/rtk
- https://github.com/trailhq/Graft
- https://github.com/DietrichGebert/ponytail
- 各选定客户端的官方文档。

主/开发分支可能描述发布版中不存在的功能。
对有疑问的选项，检查发布版、帮助或交付代码。

为每个集成建立：

客户端 | 可用项目钩子 | 兼容安装器 |
激活范围 | 状态范围 | 证明

不要混淆：
“客户端支持项目钩子”
与“该工具的安装器知道如何在项目级别安装它们”

当前版本需重新验证的检查点：

- Claude：用户设置、共享项目和本地项目。
- Cursor：用户和项目钩子；分别测试 IDE 和 CLI。
- Codex：用户/项目配置和插件激活；
  验证实际可用的钩子机制。
- Kimi：不要假设每个项目都有钩子配置；
  区分用户配置、项目指令和启动选项。
- Gemini/Copilot：如果被选中，验证它们自己的机制。

如果安装程序不遵守请求的范围：

1. 寻找合适的官方选项。
2. 否则，使用同一适配器的文档手动配置，
   仅当其协议和路径保持兼容时。
3. 否则，通过显式指令/前缀使用回退。
4. 永远不要默默切换到全局。

在添加本地等效钩子之前检查继承的全局钩子：
它们可能会累积而不是相互替换。
保留安全钩子。报告仍然激活的全局影响。

## 4. RTK

检查来源 `rtk-ai/rtk`、版本、帮助、配置和 `rtk gain`。`gain` 失败可能来自基础或权限：
这不足以证明包有问题。

如适用，使用已用的管理器安装或更新。
检查配方或包的来源及获得的版本。
避免并发安装和不必要的 PATH 变更。
不要盲目运行 `cargo install rtk`。

查阅所选版本的 `rtk init --help`。
按客户端和范围选择选项；不要系统性地复制
文档示例中的 `-g`。

不要假设 Codex 集成总是简单指令，
也不要假设它总有钩子：这取决于 RTK 版本。
还要检查初始化选项之间的不兼容性。

在实际读取的配置中，合并排除项：

    [hooks]
    exclude_commands = ["graft", "curl", "playwright"]

保留现有排除项并验证其被考虑。
如果此设置是全局的，修改前指明此影响。
通过文档机制在允许范围内禁用可选遥测。

RTK 是唯一被授权重写 shell 命令的组件。
安全、审计和审批钩子仍然适用。

未经文档兼容性，不要将 Claude 钩子复制到其他客户端。
无有效重写时，配置显式前缀 `rtk`。
避免双重钩子和双重前缀。

## 5. Graft 与 LSP

### 安装与隐私

验证包 `@nanonets/graft` 的身份、发布版本和 Node 要求。

安装在应用依赖之外的合适位置。
不要修改 package.json 或项目锁文件来安装 Graft。

从首次启动和 MCP 中应用 `DO_NOT_TRACK=1`。
如果有官方禁用遥测命令，使用之。

不要激活 Brain、账户、LLM 丰富或 `--deep`。
未经验证，不承诺零网络。

不要自动运行 `graft init`。
优先显式连接；其安装程序可能会写出仓库外。

### 真正可用的 LSP

在探索应用代码前，遵守仓库的 Graft 规则。
然后识别有用语言并查阅所选 Graft 版本的 LSP 集成。

重用已存在的兼容服务器。
仅安装必要服务器，记录版本，尽可能安装在应用依赖之外。

检查：

- 可执行文件及其版本；
- 在 Graft/MCP 进程的 PATH 中的可用性；
- 语言和工作区前提条件；
- 该 Graft 版本的支持情况。

阅读帮助后，若有以下选项，特别使用：

    graft build --lsp --no-ignore --no-gitignore
    graft check
    graft ask "Where are the main entry points and API routes, if any?" --source

用当前 shell 语法对这些命令应用 DO_NOT_TRACK。

检查选项含义：某些版本中，
`--no-ignore` 和 `--no-gitignore` 防止写入排除文件；
它们不意味着“索引被忽略的文件”。

根据所选范围显式管理 `/graft/` 的 Git 排除。
用 Git 验证。不要自动删除任何已跟踪文件。
保留注释和人工内容。

带 `--lsp` 且退出码为 0 的构建不证明使用了 LSP。
寻找针对性证据：服务器实际启动、解析结果、
丰富的边缘或文档诊断。

按语言报告：
LSP 已验证 / 可用但无观察到的丰富 / 不可用 / 不支持。

切勿在上下文中加载整个图或 wiring.json。
还要检查自动刷新后 LSP 丰富是否持续；
若无保证，记录所需的显式重建。

### MCP 与新鲜度

为每个客户端配置单一有效的 Graft 条目。
发现实际支持的文件、模式和范围。

对每个服务器，验证：
安装命令、MCP 参数、DO_NOT_TRACK、PATH 和工作目录。

不要假设 `.kimi-code/mcp.json`、`.mcp.json` 或其他文件自动加载：确认客户端机制或必要启动选项。

全局 MCP 配置仅在目标进程正确处理每个仓库时可接受。
否则，保持 MCP 在项目级别。

不要每次启动都用 `npx -y ...@latest`。
不要版本控制绝对个人路径或秘密。
不要发明通用变量 `${workspaceFolder}`。

在此配置文件中，不添加任何 Graft 钩子。
无智能 grep、grep 重定向或 Graft shell 拦截。

检查刷新及无意禁用。
刷新失败禁止将图呈现为新鲜。

迁移前检查旧集成和自动连接元数据。
仅移除已识别并备份的元素。
确认它们不会在 MCP 启动和查询后重新出现。

### Graft 统计

操作、观察使用和统计收集分开。

根据版本不同，`graft stats` 依赖会话钩子。
没有这些钩子，尽管 Graft 请求成功，仍可能出现“尚未记录会话”的提示。

不要伪造统计数据或运行 `graft init` 来让该消息消失。

如果用户需要原生统计，需暴露可用测量钩子的兼容性，并在任何激活前明确请求无钩子下的配置文件演进。

## 6. Ponytail lite

优先选择与客户端和作用域兼容的官方集成。
检查其清单、事件和依赖。

区分：
插件的安装、激活、默认模式和当前模式状态。

检查实际读取的来源：
配置、`PONYTAIL_DEFAULT_MODE`、持久状态和插件数据。
`defaultMode: lite` 并不证明旧的完整状态已被替换。

如果模式在会话间共享，需指出。
在项目作用域内，不要默默更改全局默认。
使用有文档的本地机制或通过指令使用 lite 策略。

按客户端区分：

- Claude/Codex：官方安装和激活于可用作用域。
  使用前检查子命令。
  钩子批准权仍归用户。
- Cursor：官方适配器或指令规则；避免其累积。
  如果存在 `scripts/cursor-hooks.js install --project`，
  从目标仓库根目录使用官方检出路径运行该脚本。
  无 `--project` 时，检查用户目标位置。
  检查生成路径：包含个人检出绝对路径的项目钩子不可移植，且不得提交。
- Kimi：寻找兼容的官方适配器。否则，AGENTS.md 中使用 lite 策略；仅在有用且格式和加载确认的情况下添加最小本地技能。
  将其识别为适配，不承诺原生命令或统计。
- 其他选定客户端：应用相同验证，不自动套用 Claude/Codex 事件。

保持适配器检出在已识别的版本或提交。
不要对已修改的检出执行 git pull。
不要添加状态栏或视觉指示器。

在新会话中测试实际模式。

## 7. 紧凑通用指令

合并 AGENTS.md 中由以下标记界定的块：

    <!-- agent-stack:start -->
    ...
    <!-- agent-stack:end -->

保留所有外部内容和人工添加。
不要将此安装提示复制到代理指令中。

该块必须表达：

### Graft

要理解或修改代码，先进行应用探索：
`graft ask "<精确问题>" --source`，或实际暴露的 MCP Graft 工具。

指令、技能、Git、配置和 MCP 发现可先行。
定位后，直接阅读有用部分。
调用者使用可用的跟踪命令/工具。

图表陈旧时：检查，使用 LSP 适配重建，然后新查询。
搜索失败后：针对性 graft grep，然后直接阅读或带限制说明的 bounded rg。

提供的文件、堆栈跟踪、配置或未索引语言允许直接针对性阅读。
图中缺失不证明代码或调用者不存在。

修改后：graft blast，验证 Git 基础和相关测试。
无 --name，无全图加载。
报告实际调用次数及任何错误。

### RTK

验证钩子：允许重写无双重前缀。
否则：显式前缀兼容命令。
绝不通过 RTK 传递 Graft。

完整输出：如可用，回调 --full，或代理。
不自动重跑有副作用的命令。
保留管道和重定向。

验证前：真实未压缩差异，diff --cached，diff --check 及新文件单独检查。
无自动暂存。

### Ponytail lite

正确实现请求并复用现有。
简要报告显著更简方案。
保留验证、安全、权限、无障碍、事务和必要测试。
删除或内联前验证用法。

仅在明确请求时全量，默认绝不超量。
审计不触发重设计。
安全、解析器、并发和迁移优先修正。

不要声称共享模式是会话本地。
授权全量后，验证返回 lite。
关闭不移除已注入指令。

### 加载

确认每个客户端实际如何加载这些指令。
使用有文档的最小导入/适配器。
避免重复和循环导入。

RTK 仍是唯一 shell 重写器。
此配置无 Graft 钩子。

## 8. 更新与修复

同一提示必须能无重复地重跑。

更新模式：

1. 重新读取作用域选择和先前验证状态。
2. 比较已安装版本、目标版本和不兼容变更。
3. 迁移前备份。
4. 仅更新选定组件。
5. 通过官方机制刷新插件/适配器。
6. 重新评估能力：旧回退可被同作用域内现有原生集成替代。
7. 仅迁移属于此堆栈的密钥和块。
8. 必要时重建图表并复查 LSP。
9. 重启必要的 MCP/客户端进程：现有进程可能仍运行旧版本。
10. 重放修改集成的检查和测试。

不要不必要地重装已合规组件。
不要启动机器包的全面更新。

修复模式，保持版本，除非证明不兼容且明确决定更新。

准备有针对性的回滚：先前版本、备份和精确命令。
若备份后有其他变更，不盲目恢复整个文件。

无请求变更的第二次执行不得创建任何钩子、MCP 服务器或重复指令段。

## 9. 检查与证据

单独测试：

- RTK 可执行且明确的压缩；
- 自动钩子触发、排除和原始直通；
- Graft：新鲜度、结果与仓库匹配及 LSP 丰富；
- MCP：功能性服务器且每个客户端实际加载；
- Ponytail：激活和有效模式；
- 无重复及重新出现的自连接；
- 配置的最终有效性和有效范围。

存在文件并不证明已加载。
外部 MCP 探针不证明客户端已加载。
显式 RTK 前缀不证明自动钩子。

对于每个可用且已认证的客户端，在仓库中打开新会话，
使用其常规保护，并给出此中性票据：

“在不修改代码的情况下，定位主要入口点。
如果存在 API，指出其路由挂载位置并追踪
到业务逻辑的路径。引用文件和行号。”

不要添加“使用 Graft”。
检查可见的工具调用，而非内部推理。
保持最小证据并编辑敏感数据。

如果缺少审批、登录或 UI 操作：
未测试 / 用户操作，绝不假设成功。

## 10. 交付物

在授权范围内，保持简短的维护文档：

- 操作选择、客户端和范围；
- 精确版本、来源和验证日期；
- 配置机制和限制；
- Graft/LSP 重建；
- 更新、验证和回滚流程。

对于共享安装，使用 `docs/agent-stack.md`。
对于个人/全局安装，保持机器特定信息
不包含在版本控制文件中。
仅验证模式下，交付报告而不创建这些文件。

报告关键命令、其结果、修改的文件、
备份和精确的用户操作。

清点最终钩子：
客户端、来源、范围、事件、匹配器、角色和编辑后的命令。

结尾格式：

客户端/版本 | 有效范围 | 当前配置 |
MCP 已加载 | 首次探索观察到 Graft |
LSP | RTK | Ponytail | 剩余证据/操作

使用明确状态：
已配置 / 已加载 / 观察到使用 / 未测试 / 阻止 / 不适用。

分类文件：
待审核提交 / 忽略 / 机器配置。

个人路径、密钥、缓存、图表、备份和记录
不得包含在待提交文件中。

显示最终 Git 状态和此次操作引入的变更，
并与已有变更区分。不要提交任何内容。

标签