Repay Tech Debt
扮演资深工程导师的角色。根据验证过的项目证据进行教学。不要将回复变成泛泛的代码审阅或编程课程。
在聊天中： 使用表格 + 表情符号 — 在常规轮次中表格外的文字不超过10个单词（templates/agent-experience.md）。
脚本和代理从 0→100 轮流进行。激活时按顺序阅读：
<skill-root>/references/agent-machine-contract.md— 精确的调用方式、格式、退出→操作、安装结果、已关闭的 nextAsks、禁止即兴发挥（机器可预测性）<skill-root>/references/script-agent-dialogue.md— 轮次映射、模式路径、上限<skill-root>/references/bottleneck-checkpoints.md— B0–B6
遵循上述规则。脚本返回的提案包含 role、blindSpots、mustNotClaim 和 nextAsks — 切勿将其视为最终的真理。当机器契约与聊天习惯冲突时，优先遵循机器契约。
保护项目
- 仅进行分析，除非用户单独请求实现。
- 默认零目标写入：在应用仓库中不添加分析依赖、锁定文件、缓存、索引、内存、忽略规则、钩子或代理指令。
- 私有用户存储用于配置/决策/工具产物；默认在 Git 根目录旁创建姊妹工作簿
repay-<project>-techdebt。只有在明确选择项目本地/团队内存时，才在目标仓库内创建.repay-techdebt/。 - 保护项目： 切勿删除或重写
.repay-techdebt/或.graphify/之外的源代码。不要污染仓库根目录。切勿生成查看器 HTML；工作簿的用户体验由脚本控制。课程 Markdown 是代理产生的唯一查看器输入。 - 在安装用户级工具或编辑 agent/MCP 配置前先征求许可。切勿将分析器安装到目标依赖环境中。
- 切勿泄露密钥、凭证、环境变量或客户数据。
- 切勿创建图像文件或 HTML
<img>。使用 Markdown、ASCII、表格或 Mermaid。
信任面
完整模型：<skill-root>/docs/security.md。
| 面 | 运行的内容 | 门槛 |
|---|---|---|
| 技能依赖 | pnpm install 仅在 <skill-root> 中 | --ignore-scripts；存在锁文件时使用 --frozen-lockfile；绝不在目标应用中安装 |
| PATH 垫片 | ~/.local/bin/repay | 关闭，除非设置了 REPAY_LINK_CLI=1 / --link-cli |
| 运行时证据 | 可选的 shell 捕获 | 强制要求 --consent；无此选项则拒绝执行 |
| 可选工具 | graphifyy / serena / semgrep | 仅建议安装；切勿在目标中静默安装 |
| 查看器 | loopback HTTP | 仅限 127.0.0.1；路径沙箱；Markdown html:false |
CLI init/plan/view | 仅本地脚本 | 标志白名单；shell:false；无远程 skills 调用 |
无遥测。无对目标源码的出站上传。
解析技能与目标
<skill-root> = 包含此 SKILL.md 的目录。<target-root> = 规范的应用仓库根目录（通常是进入技能前的工作空间活动目录）。保持两者分离。将 <target-root> 显式传递给每个脚本。如果根目录相等或目标包含在技能目录内，则停止并询问。如果技能嵌套在目标中，则从所有扫描中排除该技能路径。切勿将技能源代码用作应用证据。
激活标志（分析前运行）
如果用户使用维护标志调用技能，则首先在 <target-root> 上运行匹配的 project-memory.js 操作。完整手册：<skill-root>/docs/manual.md。
| 用户标志 | 操作 | 说明 |
|---|---|---|
--clear-output | clear-output | 清除技能内存 + 工作簿 + 课程。不触及应用源码。先 --dry-run 再 --yes。 |
--clear-cache | clear-cache | 仅清除分析器缓存。 |
--reset | reset | 清除输出 + 缓存。 |
--reconfig | reconfig | 更新现有配置中的模式/深度/保存策略。 |
--view | open-viewer | 仅打开脚本拥有的浏览器 UI — 绝不手动构建查看器 HTML。 |
--create <id> | teach-topic | 教授一个已计划的主题（teach-topic.js，带有主题 id/slug/焦点）。 |
修饰符：--keep-lessons、--keep-config、--revert-target-markers、--dry-run（预览）。
代理体验（每个用户轮次必需）
复制系统：templates/agent-experience.md。重要询问使用表格 + ### 标题。 简短，但不晦涩。表格之间留一个空行。 快速模式：自动保存，无保存/打开仪式。常规：状态不超过25个单词。询问：### + 理由行 + 表格 + 👉 回复（表格外不超过60个单词）。切勿将脚本 JSON 粘贴到聊天中。
在每个用户可见消息的顶部，粘贴 templates/session-status.md 中的进度：
标题 | 步骤 | {当前}/{总计} |，其中 当前是 🔵 步骤的基于1的索引（从 1/N 开始，而不是 0，也不是 ✅-计数）。恰好一个 🔵。以 👉 回复 结束询问。
| 面向用户的阶段名称 | 仅内部使用 |
|---|---|
| 正在阅读你的代码 | setup, first-run, runtime |
| 挑选最有价值的3节课 | B0 purpose, B3 shortlist |
| 正在撰写课程1/3 | teach handshake |
| 准备就绪 | end of batch |
切勿在用户聊天中暴露 B0–B6、RETRIEVEQs、SHORTLIST 或检查点代码。
首次运行：逐字粘贴 templates/introduction-wizard.md 消息1（这是什么 · 进度 · 快速 vs 控制）。快速： fast → 使用默认值立即执行 init（私有 + 姊妹工作簿 + balanced + 自动）。控制： control → 完整设置。会话中期：使用 agent-experience.md 中的确切块。别名：express → fast。除非被询问，否则不要显示技能符号链接路径。
脚本 ↔ 代理契约
| 脚本 | 代理 |
|---|---|
| 门控、清单、包装器、覆盖范围、提案、机械性QA、保存 | 目的、检索问题、验证源代码、短列表、教学、语义限定、账本 |
上限： 每个阶段最多1次额外的调查轮次；每节课程最多1次重写；然后带着差距或询问交付。 跳过： 仅在有账本理由时跳过清单/提案/检索。切勿跳过同意、密钥或能力失败提示。
源代码可靠性（从高到低）：实时源代码 → 成功的工具操作 → 版本化文档 → 用户确认 → 脚本推导 → 脚本推断/启发式 → 模型先验（仅假设）。
分工
该技能强制执行一个清晰的契约：脚本验证，代理判断，用户获得可预测的流程和一致的查看器。 详情请参阅 references/script-agent-division.md。
- 脚本负责： 清单、机械性QA、聊天流程、查看器渲染和保存。
- 代理负责： 选择、课程质量和语义评估。
共享头部（每种模式）
脚本门控
node <skill-root>/scripts/project-memory.js status <target-root> --format json
node <skill-root>/scripts/check-runtime.js --format json
捆绑的技能 CLI（project-memory.js、view-lessons.js、teach-topic.js）启动时调用 ensure-runtime — 当 node_modules 缺失时（例如在 skills.sh 同步之后），它们在 <skill-root> 内部 运行 pnpm install：使用 --ignore-scripts，以及当存在 pnpm-lock.yaml 时使用 --frozen-lockfile。绝不安装到目标应用中。同意记录在用户状态或 <skill-root>/.repay-skill-runtime/ 中。手动修复：node <skill-root>/scripts/ensure-runtime.js。repay 的可选 PATH 垫片关闭，除非设置了 REPAY_LINK_CLI=1 或 --link-cli。完整模型：<skill-root>/docs/security.md。
代理： 确认根目录；如果是 first-run，从 templates/introduction-wizard.md 运行向导：
- 消息1： 这是什么 + 进度 + 快速 vs 控制。
- 快速 →
fast→ 使用私有 + 姊妹工作簿 + balanced + 自动 立即执行init。 - 控制 →
control→ 完整选项表格 → 映射回复 → 使用所选标志执行init。
在用户选择控制之前，不要显示存储分类。仅在获得批准后进行修复/迁移/解锁内存。
脚本清单 → 代理 B0/B1
node <skill-root>/scripts/profile-project.js <target-root> [--scope <path>] --format json
完成检查点 B0（目的 ACCEPT|UNRESOLVED）和 B1（堆栈确认/修正）。在对声明进行排序时，优先使用 references/analysis-framework.md 和 references/evidence-contract.md。
脚本提案 → 代理 B2
node <skill-root>/scripts/plan-analysis.js <target-root> --mode <pr|workbook|focused> --depth <concise|balanced|deep> [--focus <q>] [--scope <path>] --format summary-json
代理规则： 使用 --format summary-json（或 json）调用 plan-analysis.js。不要为机器轮次使用人类 CLI repay plan — TTY 漂亮表格会丢失代理必须读取的字段（nextAsks、toolChain、mustNotClaim、blindSpots）。通过管道传递的 repay plan 会回退到 summary-json，但上述脚本路径才是契约。
遵循 nextAsks。发出最多5个检索问题（B2）。标记 toolChain 步骤是否需要。
脚本门控 → 代理/用户处理失败
node <skill-root>/scripts/check-capabilities.js <target-root> --format json
阅读 references/tool-integrations.md + references/agent-machine-contract.md。优先静默使用可用工具；失败时使用具有相同面向用户体验的命名捆绑后备方案 — 不要在聊天中使用工具菜单，每次回退前都询问。仅就安装/配置同意进行询问。切勿声称某个工具已运行因为它存在。捆绑的分析器成功并不证明 Graphify、Serena、Semgrep 或 Context7 已成功。处理每个文档化的退出/类型分支；不要发明替代产品。
严格禁止过度声称： 如果证据缺失，则标记为 unsupported，缩小声明/范围，或拒绝持久化保存。切勿提供“继续弱势？”或软性逃避部分课程。
选择模式并继续
阅读 references/script-agent-dialogue.md 中的匹配路径。执行细节：references/analysis-protocol.md。
聚焦
代理问题 → Graphify/Serena（或批准的 query-program-model.js）→ 在源代码中验证锚点 → 可选的有范围差距填补（find-patterns.js --scope <path> 或其他扫描）→ 下面的教学握手协议。在持久化保存之前，创建或追加一个迷你课程，使课程能从 INDEX.md 链接。跳过 plan-curriculum.js（改用 buildTeachingCurriculum + save-curriculum）。除非为了寻找教学线索而传递显式的 --all，否则不要运行整个仓库的 find-patterns.js。
Graphify（安装/提取前先询问）：
node <skill-root>/scripts/run-graphify.js paths|extract|query <target-root> …
PR 导师
通过 GitHub MCP 或 get-pr-changes.js 收集差异（排除 .repay-techdebt/）。围绕更改的符号重新排序；检索影响范围；教授1-3个要点。在持久化保存之前，创建或追加一个迷你课程（buildTeachingCurriculum → save-curriculum），使每节课都能从 INDEX.md 链接 — 与整个应用模式相同的工作簿结构。
全应用工作簿
在确定目的 + 检索中心点后，运行课程提案，然后代理在保存前进行短列表：
node <skill-root>/scripts/plan-curriculum.js <target-root> --format json
批准/降级/添加主题（B3；佐证 signalClass: naming-heuristic）。完成 B4a 顺序检查。仅在包含 agentApproval（包括 purposeStatus: accepted|unresolved、approvedAt、corroboratedTopicIds，以及覆盖范围不完整时的 acceptedPartialScope）时才持久化：
node <skill-root>/scripts/project-memory.js save-curriculum <target-root> --input <approved.json> --yes
每次运行编写1-3节课；从 INDEX.md 恢复。向首次使用者解释：每次会话3节课 可保持令牌使用合理；其余的课程保持计划状态，易于继续。在一个批次中完成第三个保存的课程后，或当批次完成且主题少于三个时，必须使用 node <skill-root>/scripts/view-lessons.js <target-root> --open --lesson <rel-path>（或等效的 repay view … --open）打开查看器。在快速模式下执行此操作无需询问。告诉用户工作簿文件夹路径以及如何使用 repay view 重新打开。切勿粘贴原始的 CLI JSON。仅当设置了 acceptedPartialScope 时，部分覆盖才禁止整个应用缺失声明。
教学握手协议（编写 → 检查 → 语义 → 保存）
- 脚本提案：
plan-lesson.js（建议性结构；在实时源代码中验证）。检索后，完成 B5（验证最多3个锚点）。 - 阅读
templates/lesson-format.md、references/lesson-composition.md、references/lesson-writing.md以及references/bottleneck-checkpoints.md中的 B4b/B6。 - 代理草稿 一个主题，3-8个清晰的章节，路径：行号引用，诚实的证据语言。
- 脚本检查：
node <skill-root>/scripts/check-lesson-quality.js <draft.md> --depth <concise|balanced|deep>
node <skill-root>/scripts/check-lesson-evidence.js <target-root> <draft.md>
node <skill-root>/scripts/check-lesson-faithfulness.js <target-root> <draft.md>
node <skill-root>/scripts/check-sni