# geny-executor - Doramagic AI Context Pack

> 定位：安装前体验与判断资产。它帮助宿主 AI 有一个好的开始，但不代表已经安装、执行或验证目标项目。

## 充分原则

- **充分原则，不是压缩原则**：AI Context Pack 应该充分到让宿主 AI 在开工前理解项目价值、能力边界、使用入口、风险和证据来源；它可以分层组织，但不以最短摘要为目标。
- **压缩策略**：只压缩噪声和重复内容，不压缩会影响判断和开工质量的上下文。

## 给宿主 AI 的使用方式

你正在读取 Doramagic 为 geny-executor 编译的 AI Context Pack。请把它当作开工前上下文：帮助用户理解适合谁、能做什么、如何开始、哪些必须安装后验证、风险在哪里。不要声称你已经安装、运行或执行了目标项目。

## Claim 消费规则

- **事实来源**：Repo Evidence + Claim/Evidence Graph；Human Wiki 只提供显著性、术语和叙事结构。
- **事实最低状态**：`supported`
- `supported`：可以作为项目事实使用，但回答中必须引用 claim_id 和证据路径。
- `weak`：只能作为低置信度线索，必须要求用户继续核实。
- `inferred`：只能用于风险提示或待确认问题，不能包装成项目事实。
- `unverified`：不得作为事实使用，应明确说证据不足。
- `contradicted`：必须展示冲突来源，不得替用户强行选择一个版本。

## 它最适合谁

- **正在使用 Claude/Codex/Cursor/Gemini 等宿主 AI 的开发者**：README 或插件配置提到多个宿主 AI。 证据：`README.md` Claim：`clm_0003` supported 0.86
- **希望把专业流程带进宿主 AI 的用户**：仓库包含 Skill 文档。 证据：`src/geny_executor/skills/bundled/batch/SKILL.md`, `src/geny_executor/skills/bundled/debug/SKILL.md`, `src/geny_executor/skills/bundled/environment/SKILL.md`, `src/geny_executor/skills/bundled/loop/SKILL.md` 等 Claim：`clm_0004` supported 0.86

## 它能做什么

- **AI Skill / Agent 指令资产库**（可做安装前预览）：项目包含可被宿主 AI 读取的 Skill 或 Agent 指令文件，可用于把专业流程带入 Claude、Codex、Cursor 等宿主。 证据：`src/geny_executor/skills/bundled/batch/SKILL.md`, `src/geny_executor/skills/bundled/debug/SKILL.md`, `src/geny_executor/skills/bundled/environment/SKILL.md`, `src/geny_executor/skills/bundled/loop/SKILL.md` 等 Claim：`clm_0001` supported 0.86
- **命令行启动或安装流程**（需要安装后验证）：项目文档中存在可执行命令，真实使用需要在本地或宿主环境中运行这些命令。 证据：`README.md` Claim：`clm_0002` supported 0.86

## 怎么开始

- `pip install geny-executor` 证据：`README.md` Claim：`clm_0005` supported 0.86, `clm_0006` supported 0.86, `clm_0007` supported 0.86, `clm_0008` supported 0.86
- `pip install geny-executor[memory]   # numpy for vector retrieval` 证据：`README.md` Claim：`clm_0006` supported 0.86
- `pip install geny-executor[all]      # everything` 证据：`README.md` Claim：`clm_0007` supported 0.86
- `pip install geny-executor[dev]      # dev/test tooling` 证据：`README.md` Claim：`clm_0008` supported 0.86
- `git clone https://github.com/CocoRoF/geny-executor.git` 证据：`README.md` Claim：`clm_0009` supported 0.86
- `pip install -e ".[dev]"` 证据：`README.md` Claim：`clm_0010` supported 0.86

## 继续前判断卡

- **当前建议**：仅建议沙盒试装
- **为什么**：项目存在安装命令、宿主配置或本地写入线索，不建议直接进入主力环境，应先在隔离环境试装。

### 30 秒判断

- **现在怎么做**：仅建议沙盒试装
- **最小安全下一步**：先跑 Prompt Preview；若仍要安装，只在隔离环境试装
- **先别相信**：真实输出质量不能在安装前相信。
- **继续会触碰**：命令执行、宿主 AI 配置、本地环境或项目文件

### 现在可以相信

- **适合人群线索：正在使用 Claude/Codex/Cursor/Gemini 等宿主 AI 的开发者**（supported）：有 supported claim 或项目证据支撑，但仍不等于真实安装效果。 证据：`README.md` Claim：`clm_0003` supported 0.86
- **适合人群线索：希望把专业流程带进宿主 AI 的用户**（supported）：有 supported claim 或项目证据支撑，但仍不等于真实安装效果。 证据：`src/geny_executor/skills/bundled/batch/SKILL.md`, `src/geny_executor/skills/bundled/debug/SKILL.md`, `src/geny_executor/skills/bundled/environment/SKILL.md`, `src/geny_executor/skills/bundled/loop/SKILL.md` 等 Claim：`clm_0004` supported 0.86
- **能力存在：AI Skill / Agent 指令资产库**（supported）：可以相信项目包含这类能力线索；是否适合你的具体任务仍要试用或安装后验证。 证据：`src/geny_executor/skills/bundled/batch/SKILL.md`, `src/geny_executor/skills/bundled/debug/SKILL.md`, `src/geny_executor/skills/bundled/environment/SKILL.md`, `src/geny_executor/skills/bundled/loop/SKILL.md` 等 Claim：`clm_0001` supported 0.86
- **能力存在：命令行启动或安装流程**（supported）：可以相信项目包含这类能力线索；是否适合你的具体任务仍要试用或安装后验证。 证据：`README.md` Claim：`clm_0002` supported 0.86
- **存在 Quick Start / 安装命令线索**（supported）：可以相信项目文档出现过启动或安装入口；不要因此直接在主力环境运行。 证据：`README.md` Claim：`clm_0005` supported 0.86, `clm_0006` supported 0.86, `clm_0007` supported 0.86, `clm_0008` supported 0.86

### 现在还不能相信

- **真实输出质量不能在安装前相信。**（unverified）：Prompt Preview 只能展示引导方式，不能证明真实项目中的结果质量。
- **宿主 AI 版本兼容性不能在安装前相信。**（unverified）：Claude、Cursor、Codex、Gemini 等宿主加载规则和版本差异必须在真实环境验证。
- **不会污染现有宿主 AI 行为，不能直接相信。**（inferred）：Skill、plugin、AGENTS/CLAUDE/GEMINI 指令可能改变宿主 AI 的默认行为。 证据：`src/geny_executor/skills/bundled/batch/SKILL.md`, `src/geny_executor/skills/bundled/debug/SKILL.md`, `src/geny_executor/skills/bundled/environment/SKILL.md`, `src/geny_executor/skills/bundled/loop/SKILL.md` 等
- **可安全回滚不能默认相信。**（unverified）：除非项目明确提供卸载和恢复说明，否则必须先在隔离环境验证。
- **真实安装后是否与用户当前宿主 AI 版本兼容？**（unverified）：兼容性只能通过实际宿主环境验证。
- **项目输出质量是否满足用户具体任务？**（unverified）：安装前预览只能展示流程和边界，不能替代真实评测。
- **安装命令是否需要网络、权限或全局写入？**（unverified）：这影响企业环境和个人环境的安装风险。 证据：`README.md`

### 继续会触碰什么

- **命令执行**：包管理器、网络下载、本地插件目录、项目配置或用户主目录。 原因：运行第一条命令就可能产生环境改动；必须先判断是否值得跑。 证据：`README.md`
- **宿主 AI 配置**：Claude/Codex/Cursor/Gemini/OpenCode 等宿主的 plugin、Skill 或规则加载配置。 原因：宿主配置会改变 AI 后续工作方式，可能和用户已有规则冲突。 证据：`src/geny_executor/skills/bundled/batch/SKILL.md`, `src/geny_executor/skills/bundled/debug/SKILL.md`, `src/geny_executor/skills/bundled/environment/SKILL.md`, `src/geny_executor/skills/bundled/loop/SKILL.md` 等
- **本地环境或项目文件**：安装结果、插件缓存、项目配置或本地依赖目录。 原因：安装前无法证明写入范围和回滚方式，需要隔离验证。 证据：`README.md`
- **宿主 AI 上下文**：AI Context Pack、Prompt Preview、Skill 路由、风险规则和项目事实。 原因：导入上下文会影响宿主 AI 后续判断，必须避免把未验证项包装成事实。

### 最小安全下一步

- **先跑 Prompt Preview**：用安装前交互式试用判断工作方式是否匹配，不需要授权或改环境。（适用：任何项目都适用，尤其是输出质量未知时。）
- **只在隔离目录或测试账号试装**：避免安装命令污染主力宿主 AI、真实项目或用户主目录。（适用：存在命令执行、插件配置或本地写入线索时。）
- **先备份宿主 AI 配置**：Skill、plugin、规则文件可能改变 Claude/Cursor/Codex 的默认行为。（适用：存在插件 manifest、Skill 或宿主规则入口时。）
- **安装后只验证一个最小任务**：先验证加载、兼容、输出质量和回滚，再决定是否深用。（适用：准备从试用进入真实工作流时。）

### 退出方式

- **保留安装前状态**：记录原始宿主配置和项目状态，后续才能判断是否可恢复。
- **准备移除宿主 plugin / Skill / 规则入口**：如果试装后行为异常，可以把宿主 AI 恢复到试装前状态。
- **记录安装命令和写入路径**：没有明确卸载说明时，至少要知道哪些目录或配置需要手动清理。
- **如果没有回滚路径，不进入主力环境**：不可回滚是继续前阻断项，不应靠信任或运气继续。

## 哪些只能预览

- 解释项目适合谁和能做什么
- 基于项目文档演示典型对话流程
- 帮助用户判断是否值得安装或继续研究

## 哪些必须安装后验证

- 真实安装 Skill、插件或 CLI
- 执行脚本、修改本地文件或访问外部服务
- 验证真实输出质量、性能和兼容性

## 边界与风险判断卡

- **把安装前预览误认为真实运行**：用户可能高估项目已经完成的配置、权限和兼容性验证。 处理方式：明确区分 prompt_preview_can_do 与 runtime_required。 Claim：`clm_0011` inferred 0.45
- **命令执行会修改本地环境**：安装命令可能写入用户主目录、宿主插件目录或项目配置。 处理方式：先在隔离环境或测试账号中运行。 证据：`README.md` Claim：`clm_0012` supported 0.86
- **待确认**：真实安装后是否与用户当前宿主 AI 版本兼容？。原因：兼容性只能通过实际宿主环境验证。
- **待确认**：项目输出质量是否满足用户具体任务？。原因：安装前预览只能展示流程和边界，不能替代真实评测。
- **待确认**：安装命令是否需要网络、权限或全局写入？。原因：这影响企业环境和个人环境的安装风险。

## 开工前工作上下文

### 加载顺序

- 先读取 how_to_use.host_ai_instruction，建立安装前判断资产的边界。
- 读取 claim_graph_summary，确认事实来自 Claim/Evidence Graph，而不是 Human Wiki 叙事。
- 再读取 intended_users、capabilities 和 quick_start_candidates，判断用户是否匹配。
- 需要执行具体任务时，优先查 role_skill_index，再查 evidence_index。
- 遇到真实安装、文件修改、网络访问、性能或兼容性问题时，转入 risk_card 和 boundaries.runtime_required。

### 任务路由

- **AI Skill / Agent 指令资产库**：先基于 role_skill_index / evidence_index 帮用户挑选可用角色、Skill 或工作流。 边界：可做安装前 Prompt 体验。 证据：`src/geny_executor/skills/bundled/batch/SKILL.md`, `src/geny_executor/skills/bundled/debug/SKILL.md`, `src/geny_executor/skills/bundled/environment/SKILL.md`, `src/geny_executor/skills/bundled/loop/SKILL.md` 等 Claim：`clm_0001` supported 0.86
- **命令行启动或安装流程**：先说明这是安装后验证能力，再给出安装前检查清单。 边界：必须真实安装或运行后验证。 证据：`README.md` Claim：`clm_0002` supported 0.86

### 上下文规模

- 文件总数：498
- 重要文件覆盖：40/498
- 证据索引条目：80
- 角色 / Skill 条目：10

### 证据不足时的处理

- **missing_evidence**：说明证据不足，要求用户提供目标文件、README 段落或安装后验证记录；不要补全事实。
- **out_of_scope_request**：说明该任务超出当前 AI Context Pack 证据范围，并建议用户先查看 Human Manual 或真实安装后验证。
- **runtime_request**：给出安装前检查清单和命令来源，但不要替用户执行命令或声称已执行。
- **source_conflict**：同时展示冲突来源，标记为待核实，不要强行选择一个版本。

## Prompt Recipes

### 适配判断

- 目标：判断这个项目是否适合用户当前任务。
- 预期输出：适配结论、关键理由、证据引用、安装前可预览内容、必须安装后验证内容、下一步建议。

```text
请基于 geny-executor 的 AI Context Pack，先问我 3 个必要问题，然后判断它是否适合我的任务。回答必须包含：适合谁、能做什么、不能做什么、是否值得安装、证据来自哪里。所有项目事实必须引用 evidence_refs、source_paths 或 claim_id。
```

### 安装前体验

- 目标：让用户在安装前感受核心工作流，同时避免把预览包装成真实能力或营销承诺。
- 预期输出：一段带边界标签的体验剧本、安装后验证清单和谨慎建议；不含真实运行承诺或强营销表述。

```text
请把 geny-executor 当作安装前体验资产，而不是已安装工具或真实运行环境。

请严格输出四段：
1. 先问我 3 个必要问题。
2. 给出一段“体验剧本”：用 [安装前可预览]、[必须安装后验证]、[证据不足] 三种标签展示它可能如何引导工作流。
3. 给出安装后验证清单：列出哪些能力只有真实安装、真实宿主加载、真实项目运行后才能确认。
4. 给出谨慎建议：只能说“值得继续研究/试装”“先补充信息后再判断”或“不建议继续”，不得替项目背书。

硬性边界：
- 不要声称已经安装、运行、执行测试、修改文件或产生真实结果。
- 不要写“自动适配”“确保通过”“完美适配”“强烈建议安装”等承诺性表达。
- 如果描述安装后的工作方式，必须使用“如果安装成功且宿主正确加载 Skill，它可能会……”这种条件句。
- 体验剧本只能写成“示例台词/假设流程”：使用“可能会询问/可能会建议/可能会展示”，不要写“已写入、已生成、已通过、正在运行、正在生成”。
- Prompt Preview 不负责给安装命令；如用户准备试装，只能提示先阅读 Quick Start 和 Risk Card，并在隔离环境验证。
- 所有项目事实必须来自 supported claim、evidence_refs 或 source_paths；inferred/unverified 只能作风险或待确认项。

```

### 角色 / Skill 选择

- 目标：从项目里的角色或 Skill 中挑选最匹配的资产。
- 预期输出：候选角色或 Skill 列表，每项包含适用场景、证据路径、风险边界和是否需要安装后验证。

```text
请读取 role_skill_index，根据我的目标任务推荐 3-5 个最相关的角色或 Skill。每个推荐都要说明适用场景、可能输出、风险边界和 evidence_refs。
```

### 风险预检

- 目标：安装或引入前识别环境、权限、规则冲突和质量风险。
- 预期输出：环境、权限、依赖、许可、宿主冲突、质量风险和未知项的检查清单。

```text
请基于 risk_card、boundaries 和 quick_start_candidates，给我一份安装前风险预检清单。不要替我执行命令，只说明我应该检查什么、为什么检查、失败会有什么影响。
```

### 宿主 AI 开工指令

- 目标：把项目上下文转成一次对话开始前的宿主 AI 指令。
- 预期输出：一段边界明确、证据引用明确、适合复制给宿主 AI 的开工前指令。

```text
请基于 geny-executor 的 AI Context Pack，生成一段我可以粘贴给宿主 AI 的开工前指令。这段指令必须遵守 not_runtime=true，不能声称项目已经安装、运行或产生真实结果。
```

## 角色 / Skill 索引

- 共索引 10 个角色 / Skill / 项目文档条目。

- **Batch Run**（skill）：Apply the same prompt or operation to a list of items in turn, collecting results. Useful for "do X to each of these files / PRs / records" tasks. 激活提示：当用户任务与“Batch Run”描述的流程高度相关时，先用它做安装前体验，再决定是否安装。 证据：`src/geny_executor/skills/bundled/batch/SKILL.md`
- **Debug Snapshot**（skill）：Capture the host's environment, working directory, recent git activity, and pipeline-relevant state so you can diagnose "what's actually happening on the machine". 激活提示：当用户任务与“Debug Snapshot”描述的流程高度相关时，先用它做安装前体验，再决定是否安装。 证据：`src/geny_executor/skills/bundled/debug/SKILL.md`
- **Self-Modifying Environment**（skill）：How to inspect and edit your OWN operating environment at runtime — system prompt, active tools, and skills — using the env tool. Use when you need to change your own capabilities turn a tool on/off, rewrite your instructions, author a new skill or save them for this session. 激活提示：当用户任务与“Self-Modifying Environment”描述的流程高度相关时，先用它做安装前体验，再决定是否安装。 证据：`src/geny_executor/skills/bundled/environment/SKILL.md`
- **Loop**（skill）：Run the same task on a recurring cron schedule. Parses interval syntax 5m, 2h, 1d, " /15 " , records the schedule, and acknowledges back to the user. 激活提示：当用户任务与“Loop”描述的流程高度相关时，先用它做安装前体验，再决定是否安装。 证据：`src/geny_executor/skills/bundled/loop/SKILL.md`
- **Lorem Ipsum**（skill）：Generate placeholder text — paragraphs, lists, code snippets, or markdown stubs. 激活提示：当用户任务与“Lorem Ipsum”描述的流程高度相关时，先用它做安装前体验，再决定是否安装。 证据：`src/geny_executor/skills/bundled/lorem-ipsum/SKILL.md`
- **Simplify**（skill）：Review code in the current working tree across three independent dimensions reuse, quality, efficiency and synthesise a small punch-list of high-value cleanups. 激活提示：当用户任务与“Simplify”描述的流程高度相关时，先用它做安装前体验，再决定是否安装。 证据：`src/geny_executor/skills/bundled/simplify/SKILL.md`
- **Skillify**（skill）：Interview the user about a workflow they keep repeating, then generate a reusable SKILL.md and write it to disk so the next session starts with the skill already loaded. 激活提示：当用户任务与“Skillify”描述的流程高度相关时，先用它做安装前体验，再决定是否安装。 证据：`src/geny_executor/skills/bundled/skillify/SKILL.md`
- **Get Unstuck**（skill）：Pause, surface the current plan + open questions, and suggest the next concrete step so the agent or operator can recover from a deadlock or analysis paralysis. 激活提示：当用户任务与“Get Unstuck”描述的流程高度相关时，先用它做安装前体验，再决定是否安装。 证据：`src/geny_executor/skills/bundled/stuck/SKILL.md`
- **Sandbox Tool Builder**（skill）：How to build a NEW tool of your own by writing its code in your sandbox, testing it, and forging it into a live, callable tool with env action="forge tool" . Use when no existing tool does what you need and you can implement it as a small script. Multiple tools + skills can be saved together as one reusable Sandbox Tool Pack. 激活提示：当用户任务与“Sandbox Tool Builder”描述的流程高度相关时，先用它做安装前体验，再决定是否安装。 证据：`src/geny_executor/skills/bundled/tool-builder/SKILL.md`
- **Verify Project Setup**（skill）：Check the host's runtime versions, required files, and recommended configs against what the project expects. 激活提示：当用户任务与“Verify Project Setup”描述的流程高度相关时，先用它做安装前体验，再决定是否安装。 证据：`src/geny_executor/skills/bundled/verify/SKILL.md`

## 证据索引

- 共索引 80 条证据。

- **geny-executor**（documentation）：! PyPI version https://img.shields.io/pypi/v/geny-executor.svg https://pypi.org/project/geny-executor/ ! Python 3.11+ https://img.shields.io/pypi/pyversions/geny-executor.svg https://pypi.org/project/geny-executor/ ! License: Apache 2.0 https://img.shields.io/badge/License-Apache 2.0-blue.svg LICENSE ! CI https://github.com/CocoRoF/geny-executor/actions/workflows/ci.yml/badge.svg https://github.com/CocoRoF/geny-executor/actions/workflows/ci.yml 证据：`README.md`
- **Batch — same operation, every item**（skill_instruction）：You're applying one operation across a list. Be uniform: every item should get the same depth and same output shape. The caller's downstream pipeline almost certainly expects regular output. 证据：`src/geny_executor/skills/bundled/batch/SKILL.md`
- **Debug — host + session diagnostic snapshot**（skill_instruction）：Debug — host + session diagnostic snapshot 证据：`src/geny_executor/skills/bundled/debug/SKILL.md`
- **Editing your own environment**（skill_instruction）：You can change your own operating environment with the env tool. Changes are session-scoped they affect only you, not other sessions or the shared template and take effect from the next turn . Every change is logged. 证据：`src/geny_executor/skills/bundled/environment/SKILL.md`
- **Loop — schedule a recurring task**（skill_instruction）：You are recording a recurring instruction. The host is responsible for the actual cron daemon — your job is to 1 parse what the user asked for, 2 translate it into a canonical cron expression, and 3 hand it off to the host's scheduler with a clear acknowledgement. 证据：`src/geny_executor/skills/bundled/loop/SKILL.md`
- **Lorem Ipsum — placeholder generator**（skill_instruction）：Lorem Ipsum — placeholder generator 证据：`src/geny_executor/skills/bundled/lorem-ipsum/SKILL.md`
- **Simplify — three-pass code review**（skill_instruction）：Run three passes over the target. Keep each pass narrow: don't let the reuse reviewer second-guess the quality reviewer, etc. After all three passes, synthesise — pick the smallest set of changes that improves the most dimensions. 证据：`src/geny_executor/skills/bundled/simplify/SKILL.md`
- **Skillify — capture a repeated workflow as a skill**（skill_instruction）：Skillify — capture a repeated workflow as a skill 证据：`src/geny_executor/skills/bundled/skillify/SKILL.md`
- **Stuck — recovery checklist**（skill_instruction）：Stop. Don't make another tool call. Read this whole skill before deciding what to do next. 证据：`src/geny_executor/skills/bundled/stuck/SKILL.md`
- **Building your own sandboxed tool**（skill_instruction）：When you lack a tool you need, write one . A sandboxed tool is just a script in your workspace that reads a JSON request on stdin and writes a JSON response on stdout. You author it, test it, then forge tool registers it as a real tool you can call from the next turn — and it always runs inside your sandbox , not on the host. 证据：`src/geny_executor/skills/bundled/tool-builder/SKILL.md`
- **Verify — host + project setup snapshot**（skill_instruction）：Verify — host + project setup snapshot 证据：`src/geny_executor/skills/bundled/verify/SKILL.md`
- **License**（source_file）：Apache License Version 2.0, January 2004 http://www.apache.org/licenses/ 证据：`LICENSE`
- **Architecture**（documentation）：Status: current for geny-executor 2.2.0. 证据：`docs/architecture.md`
- **Hosting the Claude Code CLI as a provider**（documentation）：Hosting the Claude Code CLI as a provider 证据：`docs/claude_code_cli.md`
- **geny-executor Error Codes**（documentation）：Since: 2.1.0 table verified against the enum on 2026-06-10, 2.2.0 cycle Source of truth: src/geny executor/core/errors.py ExecutorErrorCode enum 证据：`docs/error_codes.md`
- **Event catalogue**（documentation）：Generated from geny executor.events.catalog on 2026-06-20. Catalogue version: 4 · events: 115 证据：`docs/events.md`
- **Hooks — PRE/POST tool-use lifecycle**（documentation）：Hooks — PRE/POST tool-use lifecycle 证据：`docs/hooks.md`
- **EnvironmentManifest**（documentation）：Status: current for geny-executor 2.1.0. 证据：`docs/manifest.md`
- **MCP Integration**（documentation）：Status: current for geny-executor 2.1.0. 证据：`docs/mcp.md`
- **Memory Stage 2 / 18**（documentation）：Status: current for geny-executor 2.1.0. 证据：`docs/memory.md`
- **Migrating hosts to 2.2.0**（documentation）：Audience: maintainers of Geny, GAPT, and any other host carrying a compensation layer over geny-executor ≤ 2.1.x. The 2026-06-09 environment-philosophy audit mapped ~3,800 lines of host code that exists only because the library lacked an owned API. 2.2.0 ships those APIs; this guide maps each compensation module to its replacement so it can be deleted. 证据：`docs/migration-2.2.md`
- **LLM Providers**（documentation）：Status: current for geny-executor 2.1.0. Five providers shipped. 证据：`docs/providers.md`
- **2026-04-29: HostSelections — 훅/스킬/권한의 host-등록 + env-선택 패턴**（documentation）：2026-04-29: HostSelections — 훅/스킬/권한의 host-등록 + env-선택 패턴 证据：`docs/progress/2026-04-29_host_selections.md`
- **geny-executor 아키텍처 심층 검토 — Environment Management 철학 대비**（documentation）：geny-executor 아키텍처 심층 검토 — Environment Management 철학 대비 证据：`docs/reviews/2026-06-09-environment-philosophy-audit.md`
- **Builder**（source_file）：MODEL CONFIG FIELDS: set str = {f.name for f in dataclass fields ModelConfig } ⋮---- class PipelineBuilder ⋮---- def init self, name: str = "default", , api key: str = "", model: str = "" ⋮---- def with artifact self, stage: str, artifact: str - PipelineBuilder ⋮---- def with model self, model: str, kwargs: Any - PipelineBuilder ⋮---- def with system self, prompt: str = "", kwargs: Any - PipelineBuilder ⋮---- def with tools self, registry: ToolRegistry, kwargs: Any - PipelineBuilder ⋮---- def with guard self, kwargs: Any - PipelineBuilder ⋮---- def with cache self, strategy: str = "system", kwargs: Any - PipelineBuilder ⋮---- def with context self, kwargs: Any - PipelineBuilder ⋮---- def wi… 证据：`src/geny_executor/core/builder.py`
- **Alias: the agent-session layer uses "default" for the adaptive**（source_file）：VTUBER = "vtuber" WORKER ADAPTIVE = "worker adaptive" DEFAULT ALIAS = "default" ⋮---- MANIFEST PRESETS = frozenset { VTUBER, WORKER ADAPTIVE, DEFAULT ALIAS} ⋮---- WORKER ADAPTIVE EASY MAX TURNS = 1 WORKER ADAPTIVE NOT EASY MAX TURNS = 30 ⋮---- WORKER ADAPTIVE MAX TURNS = 30 VTUBER MAX TURNS = 10 ⋮---- SCAFFOLD ENTRIES SPEC: List Dict str, Any = ⋮---- PRESET SCAFFOLD OVERRIDES: Dict str, Dict str, Dict str, Any = { ⋮---- overrides = overrides or {} out: List StageManifestEntry = ⋮---- name = spec "name" ov = overrides.get name or {} strategies = dict spec.get "strategies" or {} ⋮---- def merge sorted entry lists: List StageManifestEntry - List StageManifestEntry ⋮---- merged: List StageManif… 证据：`src/geny_executor/core/manifest_factory.py`
- **Adhoc providers resolve by name via get . A provider without**（source_file）：logger = logging.getLogger name ⋮---- TAP CLOSED = object ⋮---- def error event data exc: Exception - Dict str, Any ⋮---- code str = ExecutorErrorCode.EXEC UNKNOWN.value ⋮---- code str = exc.code.value ⋮---- def pipeline config from manifest manifest: "EnvironmentManifest" - PipelineConfig ⋮---- raw = dict manifest.pipeline or {} ⋮---- def creds to client kwargs provider: str, creds: ProviderCredentials - Dict str, Any ⋮---- kwargs: Dict str, Any = {} ⋮---- extras = dict creds.extras or {} kwargs = {"api key": creds.api key} ⋮---- def validate manifest provider locations manifest: "EnvironmentManifest" - None ⋮---- strategies = entry.strategies or {} ⋮---- cfg = entry.config or {} ⋮---- def… 证据：`src/geny_executor/core/pipeline.py`
- **Built-in**（source_file）：logger = logging.getLogger name ⋮---- PRESET ENTRY POINT GROUP = "geny executor.presets" ⋮---- @dataclass class PresetInfo ⋮---- name: str description: str = "" preset type: str = "built in" tags: List str = field default factory=list environment id: Optional str = None ⋮---- @dataclass class PresetRecord ⋮---- factory: Callable ..., Pipeline ⋮---- source: str = "plugin" ⋮---- class PresetRegistry ⋮---- lock = RLock records: Dict str, PresetRecord = {} discovered: bool = False ⋮---- resolved desc = description ⋮---- first line = factory. doc .strip .splitlines resolved desc = first line 0 if first line else "" ⋮---- @classmethod def unregister cls, name: str - bool ⋮---- """Remove name from… 证据：`src/geny_executor/core/presets.py`
- **Per-stage overrides populated lazily through accessors below. We avoid**（source_file）：T In = TypeVar "T In" T Out = TypeVar "T Out" ⋮---- @dataclass class StrategyInfo ⋮---- slot name: str current impl: str available impls: List str = field default factory=list config: Dict str, Any = field default factory=dict ⋮---- @dataclass class StageDescription ⋮---- name: str order: int category: str is active: bool = True strategies: List StrategyInfo = field default factory=list ⋮---- class Strategy ABC ⋮---- @property @abstractmethod def name self - str ⋮---- @property def description self - str ⋮---- def configure self, config: Dict str, Any - None ⋮---- """Inject strategy-specific configuration.""" ⋮---- @classmethod def config schema cls - Optional Any ⋮---- """Return a :class:… 证据：`src/geny_executor/core/stage.py`
- **Ws Base**（source_file）：logger = logging.getLogger name ⋮---- HttpTransport = Callable ..., Awaitable Dict str, Any ⋮---- class QueuedWSAdapter PlatformAdapter ⋮---- def ensure queue self - asyncio.Queue ⋮---- async def fetch self - List InboundMessage ⋮---- queue = self. ensure queue ⋮---- first = await asyncio.wait for queue.get , timeout=self. idle timeout ⋮---- batch = first ⋮---- async def close self - None ⋮---- def ensure connected self - None ⋮---- async def ws loop self - None ⋮---- except Exception as exc: noqa: BLE001 — reconnect on any failure ⋮---- async def run connection self - None ⋮---- async def put self, message: Optional InboundMessage - None ⋮---- resp = await client.post url, json=json, heade… 证据：`src/geny_executor/gateway/ws_base.py`
- **Class 2 — thinking v1→v2 migration. Run first because the**（source_file）：logger = logging.getLogger name ⋮---- ANTHROPIC MODEL ALIASES: Dict str, str = { ⋮---- def resolve anthropic model model: str - str ⋮---- canonical = ANTHROPIC MODEL ALIASES.get model ⋮---- THINKING INCOMPATIBLE SAMPLING KEYS: tuple str, ... = ⋮---- TEMPERATURE DEPRECATED PREFIXES: tuple str, ... = "claude-opus-4-7", ⋮---- def model rejects sampling params model: str - bool ⋮---- THINKING ADAPTIVE ONLY PREFIXES: tuple str, ... = "claude-opus-4-7", ⋮---- def model requires adaptive thinking model: str - bool ⋮---- def translate thinking to adaptive thinking: Dict str, Any - Dict str, Any ⋮---- out = dict thinking ⋮---- DEPRECATION MSG TO KWARG KEY: Dict str, str = { ⋮---- msg = str getattr e… 证据：`src/geny_executor/llm_client/anthropic.py`
- **: Provider name stable identifier used by :class: ClientRegistry .**（source_file）：logger = logging.getLogger name ⋮---- SDK VERSION CACHE: Dict str, str = {} ⋮---- def resolve sdk version package: str - str ⋮---- cached = SDK VERSION CACHE.get package ⋮---- version = "unknown" ⋮---- module = importlib.import module package version = str getattr module, " version ", "unknown" or "unknown" ⋮---- @dataclass frozen=True class ClientCapabilities ⋮---- supports thinking: bool = False supports tools: bool = False supports streaming: bool = True supports tool choice: bool = False supports stop sequences: bool = True supports top k: bool = False supports system prompt: bool = True ⋮---- supports structured output: bool = False ⋮---- supports session continuity: bool = False ⋮----… 证据：`src/geny_executor/llm_client/base.py`
- **Credentials**（source_file）：class ConfigError GenyExecutorError ⋮---- @dataclass frozen=True class ProviderCredentials ⋮---- api key: str = "" base url: Optional str = None default headers: Optional Mapping str, str = None binary path: Optional str = None extras: Mapping str, Any = field default factory=dict auth mode: str = "auto" ⋮---- def repr self - str ⋮---- redacted = " " if self.api key else "" ⋮---- def is empty self - bool ⋮---- """True if no credential material is present at all. An explicit non- 'auto' auth mode counts as material: it is the host's declaration that a disk-resident credential subscription OAuth / setup-token state exists for this provider, which is exactly what CredentialBundle.has / preferr… 证据：`src/geny_executor/llm_client/credentials.py`
- **Google**（source_file）：class GoogleClient BaseClient ⋮---- provider = "google" sdk module = "google.genai" capabilities = ClientCapabilities ⋮---- def configure self, kwargs: Any - None ⋮---- def get client self - Any ⋮---- async def send self, request: APIRequest, , purpose: str = "" - APIResponse ⋮---- client = self. get client kwargs = self. build kwargs request ⋮---- raw = await client.aio.models.generate content kwargs ⋮---- request = self. build request ⋮---- accumulated text = "" accumulated blocks: List ContentBlock = finish reason = "" usage data: Optional Any = None ⋮---- candidate = chunk.candidates 0 ⋮---- finish reason = str candidate.finish reason ⋮---- usage data = chunk.usage metadata ⋮---- is tho… 证据：`src/geny_executor/llm_client/google.py`
- **The SDK validates the request and raises the 400 at create**（source_file）：logger = logging.getLogger name ⋮---- MAX COMPLETION TOKENS PREFIXES: tuple str, ... = ⋮---- def model requires max completion tokens model: str - bool ⋮---- class OpenAIClient BaseClient ⋮---- provider = "openai" sdk module = "openai" capabilities = ClientCapabilities ⋮---- def configure self, kwargs: Any - None ⋮---- def get client self - Any ⋮---- kwargs: Dict str, Any = {"api key": self. api key} ⋮---- msg = str getattr exc, "message", "" or exc .lower ⋮---- retry = dict kwargs ⋮---- async def send self, request: APIRequest, , purpose: str = "" - APIResponse ⋮---- client = self. get client kwargs = self. build kwargs request raw = await self. invoke with heal ⋮---- request = self. build… 证据：`src/geny_executor/llm_client/openai.py`
- **Registry**（source_file）：class ClientRegistry ⋮---- factories: Dict str, Callable , Type BaseClient = {} ⋮---- @classmethod def register cls, provider: str, factory: Callable , Type BaseClient - None ⋮---- @classmethod def get cls, provider: str - Type BaseClient ⋮---- @classmethod def available cls - List str ⋮---- def anthropic factory - Type BaseClient ⋮---- def openai factory - Type BaseClient ⋮---- def google factory - Type BaseClient ⋮---- def vllm factory - Type BaseClient ⋮---- def claude code cli factory - Type BaseClient ⋮---- def profile factory provider name: str - Callable , Type BaseClient ⋮---- """Factory for a profile-driven OpenAI-compatible local client. The client class is built from a :class: Pr… 证据：`src/geny_executor/llm_client/registry.py`
- **Vllm**（source_file）：class VLLMClient OpenAIClient ⋮---- provider = "vllm" capabilities = ClientCapabilities ⋮---- def configure capabilities self, overrides: bool - None 证据：`src/geny_executor/llm_client/vllm.py`
- **Locks**（source_file）：class LoopAgnosticLock ⋮---- slots = " lock", ⋮---- def init self - None ⋮---- async def acquire without blocking loop self - None ⋮---- async def aenter self - "LoopAgnosticLock" ⋮---- async def acquire self - bool ⋮---- def release self - None ⋮---- def locked self - bool ⋮---- all = "LoopAgnosticLock" 证据：`src/geny_executor/memory/_locks.py`
- **── MemoryProvider: descriptor + lifecycle ─────────────────────**（source_file）：logger = logging.getLogger name ⋮---- class CompositeMemoryProvider MemoryProvider ⋮---- NAME = "composite" VERSION = "1.0.0" ⋮---- ── MemoryProvider: descriptor + lifecycle ───────────────────── ⋮---- @property def descriptor self - MemoryDescriptor ⋮---- @property def routing self - LayerRouting ⋮---- async def initialize self - None ⋮---- async def close self - None ⋮---- def set hooks self, hooks: MemoryHooks - None ⋮---- """Forward MemoryHooks to every distinct scope provider. The composite itself doesn't own STM/Notes — it only routes layer calls to underlying scope providers session, user curated, global . Hooks must reach the actual store layer where after record turn / after note w… 证据：`src/geny_executor/memory/composite/provider.py`
- **Google**（source_file）：GOOGLE DIMS = { ⋮---- class GoogleEmbeddingClient EmbeddingClient ⋮---- @property def descriptor self - EmbeddingDescriptor ⋮---- async def embed self, texts: Sequence str - List List float ⋮---- client = self. ensure client ⋮---- resp = await client.aio.models.embed content ⋮---- embeds = getattr resp, "embeddings", None ⋮---- vectors: List List float = ⋮---- values = getattr item, "values", None ⋮---- async def close self - None ⋮---- def ensure client self ⋮---- all = "GoogleEmbeddingClient" 证据：`src/geny_executor/memory/embedding/google.py`
- **SDK response: data: List Embedding embedding: List float**（source_file）：logger = logging.getLogger name ⋮---- MAX BATCH SIZE = 2048 ⋮---- MAX EMBED BYTES = 8192 TRUNCATE TO BYTES = 8000 truncation warned = False ⋮---- def bound input text: str - str ⋮---- encoded = text.encode "utf-8" ⋮---- truncation warned = True ⋮---- OPENAI DIMS = { ⋮---- class OpenAIEmbeddingClient EmbeddingClient ⋮---- @property def descriptor self - EmbeddingDescriptor ⋮---- async def embed self, texts: Sequence str - List List float ⋮---- client = self. ensure client out: List List float = ⋮---- texts = bound input t for t in texts ⋮---- batch = list texts i : i + MAX BATCH SIZE ⋮---- resp = await client.embeddings.create input=batch, model=self. model ⋮---- SDK response: data: List Emb… 证据：`src/geny_executor/memory/embedding/openai.py`
- **Registry**（source_file）：SUPPORTED = frozenset {"openai", "voyage", "google", "local"} ⋮---- p = provider.lower .strip ⋮---- opts = dict options or {} ⋮---- all = "create embedding client" 证据：`src/geny_executor/memory/embedding/registry.py`
- **Facts**（source_file）：logger = logging.getLogger name ⋮---- CompleteStructured = Callable str, Dict str, Any , Awaitable Optional Dict str, Any ⋮---- FACTS FILENAME = " facts .md" FACTS CATEGORY = "critical" ⋮---- FACT KINDS = ⋮---- IMPORTANCE LEVELS = "critical", "high", "medium", "low" ⋮---- FACT EXTRACTION SCHEMA: Dict str, Any = { ⋮---- MEMORY ENGINE SYSTEM PROMPT = ⋮---- @dataclass class Fact ⋮---- id: str kind: str statement: str importance: str = "medium" evidence: str = "" status: str = "active" created: str = "" updated: str = "" ⋮---- def to dict self - Dict str, Any ⋮---- @classmethod def from dict cls, data: Dict str, Any - Optional "Fact" ⋮---- fid = str data.get "id", "" .strip statement = str data… 证据：`src/geny_executor/memory/facts.py`
- **Presets**（source_file）：parts = base prompt.rstrip if base prompt else ⋮---- blocks = PersonaBlock prompt ⋮---- class GenyPresets ⋮---- """Worker easy — single-turn Q&A with memory context. Active stages: Input → Context → System → Guard → Cache → API → Token → Parse → Memory → Yield Best for: simple questions that need memory context but no tools or loops. Args: provider: Live MemoryProvider typically composite . hooks: Retrieval policy + post-write callbacks. When provided, also installed onto the provider via set hooks . llm gate: Optional per-turn predicate; False skips memory. host memory clause: Concrete tool catalogue + ladder description the host wants appended after the executor's generic memory-usage cla… 证据：`src/geny_executor/memory/presets.py`
- **Interaction fields D4 — promoted from metadata to typed surface**（source_file）：class Layer str, enum.Enum ⋮---- STM = "stm" LTM = "ltm" NOTES = "notes" VECTOR = "vector" INDEX = "index" CURATED = "curated" GLOBAL = "global" ⋮---- class Capability str, enum.Enum ⋮---- READ = "read" WRITE = "write" SEARCH = "search" LINK = "link" PROMOTE = "promote" REINDEX = "reindex" SNAPSHOT = "snapshot" REFLECT = "reflect" SUMMARIZE = "summarize" ⋮---- class Scope str, enum.Enum ⋮---- EPHEMERAL = "ephemeral" SESSION = "session" USER = "user" TENANT = "tenant" ⋮---- class Importance str, enum.Enum ⋮---- CRITICAL = "critical" HIGH = "high" MEDIUM = "medium" LOW = "low" ⋮---- @property def boost self - float ⋮---- @dataclass frozen=True class NoteRef ⋮---- filename: str scope: Scope =… 证据：`src/geny_executor/memory/provider.py`
- **Wire incremental sidecar refresh — every successful**（source_file）：logger = logging.getLogger name ⋮---- class FileMemoryProvider MemoryProvider ⋮---- NAME = "file" VERSION = "1.0.0" ⋮---- Wire incremental sidecar refresh — every successful write/update/delete rewrites the affected category shard plus the root summary EXEC-5 / D6 . ⋮---- Auto-vector wiring — every successful note write/update forwards the body to the vector store. The indexer is plugged in after the notes store is constructed because the vector store depends on the notes store's body lookup. ⋮---- def set hooks self, hooks: MemoryHooks - None ⋮---- """Swap the policy callbacks post-construction. Useful when the host installs business hooks after the provider has been wired into the pipelin… 证据：`src/geny_executor/memory/providers/file/provider.py`
- **Hook bag — the SQL backend doesn't fire after callbacks**（source_file）：logger = logging.getLogger name ⋮---- DSN = Union str, Path ⋮---- class SQLMemoryProvider MemoryProvider ⋮---- NAME = "sql" VERSION = "1.0.0" ⋮---- Hook bag — the SQL backend doesn't fire after callbacks yet deployed file provider drives the hook chain , but the attribute is held so the contract surface is uniform across provider impls. Future PR will plumb hooks into the SQL store layers when SQL backend gets production traffic. ⋮---- def set hooks self, hooks: "MemoryHooks" - None ⋮---- def build vector store self - Optional SQLVectorStore ⋮---- async def lookup note text self, filename: str - Optional str ⋮---- note = await self. notes.read filename ⋮---- @property def descriptor self -… 证据：`src/geny_executor/memory/providers/sql/provider.py`
- **text-only flatten**（source_file）：logger = logging.getLogger name ⋮---- def layer cap hooks: MemoryHooks, layer: str - int ⋮---- ratio = hooks.layer budget ratio.get layer, 0.0 ⋮---- class MemoryAwareRetriever MemoryRetriever ⋮---- @property def name self - str ⋮---- @property def description self - str ⋮---- async def retrieve self, query: str, state: PipelineState - List MemoryChunk ⋮---- hooks = self. hooks ⋮---- search query = query : hooks.search chars .strip ⋮---- chunks: List MemoryChunk = total = 0 budget = hooks.max inject chars breakdown: Dict str, int = {} ⋮---- def record layer: str, before: int - None ⋮---- before = total total = await self. load recent turns chunks, total, budget, hooks ⋮---- total = await sel… 证据：`src/geny_executor/memory/retriever.py`
- **Rollup**（source_file）：logger = logging.getLogger name ⋮---- Summarize = Callable str , Awaitable str ⋮---- CompleteStructured = Callable str, Dict str, Any , Awaitable Optional Dict str, Any ⋮---- def string array - Dict str, Any ⋮---- SEGMENT DIGEST SCHEMA: Dict str, Any = { ⋮---- EVERGREEN SCHEMA: Dict str, Any = { ⋮---- def bullets items: Any - List str ⋮---- out: List str = ⋮---- text = str item .strip ⋮---- def render segment digest data: Dict str, Any - str ⋮---- """Deterministic markdown for a schema-bound rolling digest.""" sections = lines: List str = summary = str data.get "summary", "" .strip ⋮---- lines += " ⋮---- rows = bullets data.get key ⋮---- content = getattr turn, "content", "" or "" ⋮---- pie… 证据：`src/geny_executor/memory/rollup.py`
- **Qdrant Store**（source_file）：logger = logging.getLogger name ⋮---- POINT NAMESPACE = uuid.UUID "6f9d35b2-8a54-4f0e-9c39-2f6a1f6f0f3e" ⋮---- @dataclass slots=True class DocumentChunk ⋮---- text: str metadata: Dict str, Any = field default factory=dict ⋮---- def point id collection: str, filename: str, chunk index: int - str ⋮---- @property def descriptor self - EmbeddingDescriptor ⋮---- def get qdrant self - Any ⋮---- async def ensure collection self - None ⋮---- qdrant = self. get qdrant dim = int self.descriptor.dimension ⋮---- info = await qdrant.get collection self. collection existing = info.config.params.vectors existing dim = getattr existing, "size", None ⋮---- @staticmethod def ref filter filename: str - Any ⋮-… 证据：`src/geny_executor/memory/vector/qdrant_store.py`
- **Registry**（source_file）：logger = logging.getLogger name ⋮---- @dataclass frozen=True class NotificationEndpoint ⋮---- name: str url: str headers: Optional Dict str, str = None description: Optional str = None ⋮---- class NotificationEndpointRegistry ⋮---- def init self - None ⋮---- def register self, endpoint: NotificationEndpoint - None ⋮---- def get self, name: str - Optional NotificationEndpoint ⋮---- def list self - List NotificationEndpoint ⋮---- all = "NotificationEndpoint", "NotificationEndpointRegistry" 证据：`src/geny_executor/notifications/registry.py`
- **PR-B.5.1: ACCEPT EDITS / DONT ASK promote ASK rules to ALLOW.**（source_file）：class ToolLike Protocol ⋮---- @property def name self - str: ... ⋮---- async def prepare permission matcher self, input: Dict str, Any - Callable str , bool : ... ⋮---- def sort by source priority rules: List PermissionRule - List PermissionRule ⋮---- priority index = {src: i for i, src in enumerate SOURCE PRIORITY } ⋮---- matcher = await tool.prepare permission matcher tool input ⋮---- ordered = sort by source priority rules ⋮---- reason = PR-B.5.1: ACCEPT EDITS / DONT ASK promote ASK rules to ALLOW. DENY rules pass through untouched on both modes. promoted = maybe promote ask rule, mode, tool.name ⋮---- 2. PLAN mode auto-escalation runs after rule walk so an explicit ALLOW at any source-p… 证据：`src/geny_executor/permission/matrix.py`
- **── Import statements ────────────────────────**（source_file）：class ScriptSecurityError Exception ⋮---- FORBIDDEN MODULES: FrozenSet str = frozenset ⋮---- ALLOWED BUILTINS: FrozenSet str = frozenset ⋮---- FORBIDDEN CALLS: FrozenSet str = frozenset ⋮---- def validate script code: str - List str ⋮---- violations: List str = ⋮---- tree = ast.parse code ⋮---- ── Import statements ──────────────────────── ⋮---- base = alias.name.split "." 0 ⋮---- base = node.module.split "." 0 ⋮---- ── Dangerous function calls ───────────────── ⋮---- func = node.func name = None ⋮---- name = func.id ⋮---- name = func.attr ⋮---- ── Attribute access to dunder ──────────────── ⋮---- dangerous dunders = { ⋮---- def check script code: str - None ⋮---- """Raise :class: ScriptSec… 证据：`src/geny_executor/security/script_sandbox.py`
- **Section Registry**（source_file）：logger = logging.getLogger name ⋮---- REGISTRY: Dict str, Callable ..., Any = {} ⋮---- def register section name: str, schema: Callable ..., Any - None ⋮---- def get section schema name: str - Optional Callable ..., Any ⋮---- def list section names - List str ⋮---- def reset section registry - None ⋮---- all = 证据：`src/geny_executor/settings/section_registry.py`
- **Registry**（source_file）：class SkillRegistry ⋮---- def init self - None ⋮---- def register self, skill: Skill - "SkillRegistry" ⋮---- existing = self. skills skill.id ⋮---- def register many self, skills: Iterable Skill - "SkillRegistry" ⋮---- def unregister self, skill id: str - None ⋮---- def clear self - None ⋮---- def get self, skill id: str - Optional Skill ⋮---- def list all self - List Skill ⋮---- def list ids self - List str ⋮---- def len self - int ⋮---- def contains self, skill id: str - bool 证据：`src/geny_executor/skills/registry.py`
- **Registry**（source_file）：logger = logging.getLogger name ⋮---- class SlashCommandRegistry ⋮---- def init self - None ⋮---- def register self, cmd: SlashCommand - None ⋮---- def deregister self, name: str - bool ⋮---- cmd = self. commands.pop name, None ⋮---- def resolve self, name: str - Optional SlashCommand ⋮---- def list all self - List SlashCommand ⋮---- seen = set out: List SlashCommand = ⋮---- def list by category self, category: SlashCategory - List SlashCommand ⋮---- def discover paths self, path: Path - int ⋮---- @property def discovery paths self - List Path ⋮---- DEFAULT: Optional SlashCommandRegistry = None ⋮---- def get default registry - SlashCommandRegistry ⋮---- DEFAULT = SlashCommandRegistry ⋮----… 证据：`src/geny_executor/slash_commands/registry.py`
- **Normalize**（source_file）：class InputStage Stage Any, NormalizedInput ⋮---- @property def validator self - InputValidator ⋮---- @property def normalizer self - InputNormalizer ⋮---- @property def name self - str ⋮---- @property def order self - int ⋮---- @property def category self - str ⋮---- def get strategy slots self - Dict str, StrategySlot ⋮---- async def execute self, input: Any, state: PipelineState - NormalizedInput ⋮---- error = self. validator.validate input ⋮---- Normalize normalized = self. normalizer.normalize input ⋮---- Add user message to state 证据：`src/geny_executor/stages/s01_input/artifact/default/stage.py`
- **Stage**（source_file）：all = "InputStage" 证据：`src/geny_executor/stages/s01_input/stage.py`
- **Extract text from content blocks could be multimodal**（source_file）：class ContextStage Stage Any, Any ⋮---- @property def provider self - Optional MemoryProvider ⋮---- @provider.setter def provider self, value: Optional MemoryProvider - None ⋮---- @property def strategy self - ContextStrategy ⋮---- @property def compactor self - HistoryCompactor ⋮---- @property def retriever self - MemoryRetriever ⋮---- @property def name self - str ⋮---- @property def order self - int ⋮---- @property def category self - str ⋮---- def get strategy slots self - Dict str, StrategySlot ⋮---- def get config schema self - ConfigSchema ⋮---- def get config self - Dict str, Any ⋮---- def update config self, config: Dict str, Any - None ⋮---- def should bypass self, state: Pipeline… 证据：`src/geny_executor/stages/s02_context/artifact/default/stage.py`
- **Stage**（source_file）：all = "ContextStage" 证据：`src/geny_executor/stages/s02_context/stage.py`
- 其余 20 条证据见 `AI_CONTEXT_PACK.json` 或 `EVIDENCE_INDEX.json`。

## 宿主 AI 必须遵守的规则

- **把本资产当作开工前上下文，而不是运行环境。**：AI Context Pack 只包含证据化项目理解，不包含目标项目的可执行状态。 证据：`README.md`, `src/geny_executor/skills/bundled/batch/SKILL.md`, `src/geny_executor/skills/bundled/debug/SKILL.md`
- **回答用户时区分可预览内容与必须安装后才能验证的内容。**：安装前体验的消费者价值来自降低误装和误判，而不是伪装成真实运行。 证据：`README.md`, `src/geny_executor/skills/bundled/batch/SKILL.md`, `src/geny_executor/skills/bundled/debug/SKILL.md`

## 用户开工前应该回答的问题

- 你准备在哪个宿主 AI 或本地环境中使用它？
- 你只是想先体验工作流，还是准备真实安装？
- 你最在意的是安装成本、输出质量、还是和现有规则的冲突？

## 验收标准

- 所有能力声明都能回指到 evidence_refs 中的文件路径。
- AI_CONTEXT_PACK.md 没有把预览包装成真实运行。
- 用户能在 3 分钟内看懂适合谁、能做什么、如何开始和风险边界。

---

## Doramagic Context Augmentation

下面内容用于强化 Repomix/AI Context Pack 主体。Human Manual 只提供阅读骨架；踩坑日志会被转成宿主 AI 必须遵守的工作约束。

## Human Manual 骨架

使用规则：这里只是项目阅读路线和显著性信号，不是事实权威。具体事实仍必须回到 repo evidence / Claim Graph。

宿主 AI 硬性规则：
- 不得把页标题、章节顺序、摘要或 importance 当作项目事实证据。
- 解释 Human Manual 骨架时，必须明确说它只是阅读路线/显著性信号。
- 能力、安装、兼容性、运行状态和风险判断必须引用 repo evidence、source path 或 Claim Graph。

- **21 阶段管道与双抽象架构总览**：importance `high`
  - source_paths: src/geny_executor/core/pipeline.py, src/geny_executor/core/builder.py, src/geny_executor/core/presets.py, src/geny_executor/core/stage.py, src/geny_executor/core/manifest_factory.py
- **LLM 客户端与多提供者抽象**：importance `high`
  - source_paths: src/geny_executor/llm_client/registry.py, src/geny_executor/llm_client/credentials.py, src/geny_executor/llm_client/anthropic.py, src/geny_executor/llm_client/openai.py, src/geny_executor/llm_client/google.py
- **记忆子系统、Fact Ledger 与向量后端**：importance `high`
  - source_paths: src/geny_executor/memory/_locks.py, src/geny_executor/memory/facts.py, src/geny_executor/memory/rollup.py, src/geny_executor/memory/retriever.py, src/geny_executor/memory/composite/provider.py
- **工具系统、MCP 集成与扩展机制**：importance `medium`
  - source_paths: src/geny_executor/tools/base.py, src/geny_executor/tools/registry.py, src/geny_executor/tools/provider.py, src/geny_executor/tools/composer.py, src/geny_executor/tools/sandbox.py

## Repo Inspection Evidence / 源码检查证据

- repo_clone_verified: true
- repo_inspection_verified: true
- repo_commit: `52028e50edd34ab1a2b8d57f133212dd1d17e762`
- inspected_files: `README.md`, `pyproject.toml`, `uv.lock`, `docs/MEMORY_SPEC.yaml`, `docs/architecture.md`, `docs/claude_code_cli.md`, `docs/error_codes.md`, `docs/events.md`, `docs/hooks.md`, `docs/manifest.md`, `docs/mcp.md`, `docs/memory.md`, `docs/migration-2.2.md`, `docs/progress/2026-04-29_host_selections.md`, `docs/providers.md`, `docs/reviews/2026-06-09-environment-philosophy-audit.md`, `src/geny_executor/__init__.py`, `src/geny_executor/channels/__init__.py`, `src/geny_executor/channels/built_in.py`, `src/geny_executor/channels/factory.py`

宿主 AI 硬性规则：
- 没有 repo_clone_verified=true 时，不得声称已经读过源码。
- 没有 repo_inspection_verified=true 时，不得把 README/docs/package 文件判断写成事实。
- 没有 quick_start_verified=true 时，不得声称 Quick Start 已跑通。

## Doramagic Pitfall Constraints / 踩坑约束

这些规则来自 Doramagic 发现、验证或编译过程中的项目专属坑点。宿主 AI 必须把它们当作工作约束，而不是普通说明文字。

### Constraint 1: 可能修改宿主 AI 配置

- Trigger: 项目面向 Claude/Cursor/Codex/Gemini/OpenCode 等宿主，或安装命令涉及用户配置目录。
- Host AI rule: 列出会写入的配置文件、目录和卸载/回滚步骤。
- Why it matters: 安装可能改变本机 AI 工具行为，用户需要知道写入位置和回滚方法。
- Evidence: capability.host_targets | https://github.com/CocoRoF/geny-executor | host_targets=mcp_host, claude_code, claude, chatgpt
- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。

### Constraint 2: 能力判断依赖假设

- Trigger: README/documentation is current enough for a first validation pass.
- Host AI rule: 将假设转成下游验证清单。
- Why it matters: 假设不成立时，用户拿不到承诺的能力。
- Evidence: capability.assumptions | https://github.com/CocoRoF/geny-executor | README/documentation is current enough for a first validation pass.
- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。

### Constraint 3: 失败模式：migration: 1.21.0 — root _index.json as bounded folder-tree summary

- Trigger: Developers should check this migration risk before relying on the project: 1.21.0 — root _index.json as bounded folder-tree summary
- Host AI rule: Before packaging this project, run the relevant install/config/quickstart check for: 1.21.0 — root _index.json as bounded folder-tree summary. Context: Observed during version upgrade or migration.
- Why it matters: Upgrade or migration may change expected behavior: 1.21.0 — root _index.json as bounded folder-tree summary
- Evidence: failure_mode_cluster:github_release | https://github.com/CocoRoF/geny-executor/releases/tag/v1.21.0 | 1.21.0 — root _index.json as bounded folder-tree summary
- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。

### Constraint 4: 维护活跃度未知

- Trigger: 未记录 last_activity_observed。
- Host AI rule: 补 GitHub 最近 commit、release、issue/PR 响应信号。
- Why it matters: 新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。
- Evidence: evidence.maintainer_signals | https://github.com/CocoRoF/geny-executor | last_activity_observed missing
- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。

- Trigger: no_demo
- Evidence: downstream_validation.risk_items | https://github.com/CocoRoF/geny-executor | no_demo; severity=medium
- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。

### Constraint 6: 存在评分风险

- Trigger: no_demo
- Why it matters: 风险会影响是否适合普通用户安装。
- Evidence: risks.scoring_risks | https://github.com/CocoRoF/geny-executor | no_demo; severity=medium
- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。

### Constraint 7: 失败模式：performance: v2.46.0 — Fact Ledger + schema-bound memory

- Trigger: Developers should check this performance risk before relying on the project: v2.46.0 — Fact Ledger + schema-bound memory
- Host AI rule: Before packaging this project, run the relevant install/config/quickstart check for: v2.46.0 — Fact Ledger + schema-bound memory. Context: Source discussion did not expose a precise runtime context.
- Why it matters: Upgrade or migration may change expected behavior: v2.46.0 — Fact Ledger + schema-bound memory
- Evidence: failure_mode_cluster:github_release | https://github.com/CocoRoF/geny-executor/releases/tag/v2.46.0 | v2.46.0 — Fact Ledger + schema-bound memory
- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。

### Constraint 8: 失败模式：performance: v2.46.1 — Fact Ledger round-trip fix

- Trigger: Developers should check this performance risk before relying on the project: v2.46.1 — Fact Ledger round-trip fix
- Host AI rule: Before packaging this project, run the relevant install/config/quickstart check for: v2.46.1 — Fact Ledger round-trip fix. Context: Source discussion did not expose a precise runtime context.
- Why it matters: Upgrade or migration may change expected behavior: v2.46.1 — Fact Ledger round-trip fix
- Evidence: failure_mode_cluster:github_release | https://github.com/CocoRoF/geny-executor/releases/tag/v2.46.1 | v2.46.1 — Fact Ledger round-trip fix
- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。

### Constraint 9: 失败模式：performance: v2.47.0 — qdrant knowledge-vault vector backend

- Trigger: Developers should check this performance risk before relying on the project: v2.47.0 — qdrant knowledge-vault vector backend
- Host AI rule: Before packaging this project, run the relevant install/config/quickstart check for: v2.47.0 — qdrant knowledge-vault vector backend. Context: Source discussion did not expose a precise runtime context.
- Why it matters: Upgrade or migration may change expected behavior: v2.47.0 — qdrant knowledge-vault vector backend
- Evidence: failure_mode_cluster:github_release | https://github.com/CocoRoF/geny-executor/releases/tag/v2.47.0 | v2.47.0 — qdrant knowledge-vault vector backend
- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。

### Constraint 10: 失败模式：performance: v2.48.2 — memory lock deadlock fix

- Trigger: Developers should check this performance risk before relying on the project: v2.48.2 — memory lock deadlock fix
- Host AI rule: Before packaging this project, run the relevant install/config/quickstart check for: v2.48.2 — memory lock deadlock fix. Context: Source discussion did not expose a precise runtime context.
- Why it matters: Upgrade or migration may change expected behavior: v2.48.2 — memory lock deadlock fix
- Evidence: failure_mode_cluster:github_release | https://github.com/CocoRoF/geny-executor/releases/tag/v2.48.2 | v2.48.2 — memory lock deadlock fix
- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。