YHWH

YHWH 是面向 Windows 11 + WSL2 的便携式 Kether 治理规则与 Pi 执行环境，适合希望为 AI 编码工作流配置受控 worker、沙箱和 LSP 工具的开发者与维护者。它提供宿主接入配置、主代理规则、资源限制与结果校验；不安装主代理客户端，也不代表所有宿主或模型均已实机验证。

快速开始： 查看一键安装（需 Windows 11、WSL2 与硬件虚拟化），或先读常见客户端接入；项目结构见下方，安装细节与验证边界见安装和验证与卸载。

角色友好名称与内部 Kether ID 的对应关系见Pi 角色预设指南 / English。

可切换的 worker 硬限制。 新源码默认在 YHWH 受管入口拒绝非 Luna worker，保留受控 reviewer/心跳例外；独立无头 CLI 模型执行在严格模式下停用。宿主可通过 YHWH_WORKER_ENFORCEMENT=strict|off 切换，任务不能覆盖。已有服务需要单独升级；不包含对宿主自身终端/编辑器的操作系统隔离。详见开关与约束范围。

主代理只负责思考与调度： Astra（或宿主选择的主模型）负责方案、调度、补丁整合与验收；代码、测试和实现修复由 Pi 子代理编写，原生 worker 默认 Luna/medium，并按任务复杂度显式选择 low、high 或 max。子代理失败不自动回退为主代理编码。该策略是宿主指令约束，不能禁用所有客户端的编辑工具；详见职责与失败处理与思考档位和交付预算。

写入任务分级： 新源码按可观察条件将整项改动分为 T0/T1/T2。T0 实现后验证，T1 再加独立后评审，T2 还须在写入前通过 linked 前评审。网关要求显式分级与声明，将层级记录到账本，并拒绝缺失分级、低报及缺少前评审的 T2；T0 返回补丁还受单文件、20 行上限校验。声明中的风险语义仍由主代理核实；现有服务需要单独升级。见分级规则。

子代理监管心跳： 本地计时器提供不调用模型的心跳，并单独记录最近执行进度；静默不触发自动重试。它不证明远端模型健康，也不自动唤醒主代理；详见心跳说明与部署边界。

协作式小任务包（源码命令行）： 可将同一目标拆成 2–4 个文件范围互不冲突的 Pi 子任务，共享任务身份并由现有网关并发调度；主代理仍负责结果汇总与验收。查看使用方法与验证边界。

交付诊断： 新增思考、正文、工具事件计数及最近活动时间，帮助解释子代理超时；不保存原始内容，不改变预算或成功判定。现有安装需升级；它不是完成等待接口。详见诊断字段与证据边界。

连续调用改进：HeadlessBatchEvents 实时显示各项阶段、等待状态和结果；会话缓存减少重复文件读取与哈希，保留每次版本检查。整批执行前校验，同会话串行调用，失败即停止；报告缓存命中及分段耗时。详见操作与验收边界。

v0.12 工作流优化： CLI 实机回显验收、连续批次与耗时证据、可选 Windows Job Object 清理、受管插件升级/回滚、Git 变更影响候选及 Windows CI 配置。Antigravity 路径留空、默认禁用；CI 尚有失败项。源码能力与已部署/已发布状态分别记录，见操作与验收指南。

新增可选特性：Codex、Claude Code、Antigravity 官方 CLI 无头主代理入口，包含版本锁定、统一结果、运行预算和发布/本地文件比对。现有 Pi 路由保持不变，默认不启用客户端。见 使用说明。

v0.15.0 汇总运行时质量与宿主验收改进：只读 fixture、新文件父目录、任务预检警告、hostEvidence 修复、原字节补丁策略、分级治理及 Claude CLI reviewer。发布包由 Git 提交生成插件版本；本地新版已通过零漂移和两条路线探针，此版本不作量化提速声明。沿用此前授权的发布例外，不捆绑第三方依赖，并保留固定版 pi-lsp-extension 1.3.0 的许可缺口说明。详见发布说明。

开发背景、架构演进、关键决策及历史验证边界见 架构开发历史；对应的脱敏记录见 历史证据索引。

本仓库的 README 统一采用中英文双版本，并在顶部提供语言切换按钮；新增或修改时同步维护两版。维护约定见 AGENTS.md（仓库文件，不随安装包分发）。

0.7 受控 API 配置： 支持 OpenCode Go、CommandCode、OpenRouter 和自定义 HTTPS 平台。宿主显式配置后选择可选 API 路由，保留 Luna/Sonnet 5 与 max 绑定、审查者无工具、无自动降级。新增 Configure-Providers.cmd；见平台配置指南。真实账号与付费心跳尚未验证。

0.8 API key 加密： Anthropic 和聚合平台密钥使用 Windows DPAPI 用户级加密；运行时经私有管道传递，不生成 API 明文凭据文件。升级后运行 Migrate-API-Keys.cmd 迁移旧格式。见配置与迁移指南。

0.10 项目长期知识： .yhwh/memory/ 保存有来源的 Markdown 知识，支持草稿、确认和废弃状态。只读 project_memory 工具提供中英文检索、源文件变化检测，以及已暂存、未暂存和未跟踪条目的 Git 差异检查。更新由主代理已有文件权限完成，不自动提交；需要运行机器安装 Git，已有服务需升级才可发现新工具。见使用与管理指南。

仓库结构

0.11 代码关系持续记忆。 新增 .yhwh/code-graph/index.json，首批支持 JS/TS（含 JSX/TSX）与 Python 的文件、类、函数及语法关系。只读 code_graph 可检索关系和反查相对导入的影响范围；宿主 CLI 按文件散列增量刷新，支持显式限时监听。未解析调用、语法错误和过期状态会明确报告，不代表完整语义调用图。见使用、Git 管理与限制。维护者本机 Pi 已更新并通过实际 MCP 与增量刷新验证；已随 v0.11.0 发布。

**0.5 多宿主接入：**共 18 个宿主 ID，新增 Cursor、VS Code/Copilot、Windsurf Cascade、Cline、Roo Code、Gemini CLI、Kiro、Zed、Continue 和 LM Studio，保留已有 Codex、Cherry Studio、OpenCode、DeepSeek Harness、Claude 与通用配置。主模型在宿主中选择。见常见客户端指南与多宿主指南；配置和协议测试不等于客户端界面与完整治理链已验证。

• payload/pi-dispatch/：网关源码、插件、编辑器桥接、测试和模块生命周期实现。
• payload/workflow-skills/：当前安装 kether-governance 主代理治理技能；其余角色与路由技能仅保留为历史资料，实际 worker 角色由 Pi 网关注入。
• templates/AGENTS.kether.md：精简的全局规则入口。
• templates/agent-references/：按需加载的治理、路由、契约、认证和证据规则。
• install/：安装、校验、宿主认证配置与 WSL 沙箱部署工具。

当前规则固定原生 worker 使用 Luna，思考档位由主代理按任务选择，默认为 medium；reviewer 保持 Sonnet/max。实际可用性仍由目标账号、模型服务及网关能力检查决定。生命周期管理支持按依赖启动、失败回收和逆序释放；dispatch/LSP 适配器仅能由可信宿主在空闲时替换。接口见 模块生命周期。

仓库不包含凭据、个人运行配置、请求账本、审计日志、缓存、依赖目录或机器备份。图片流程引用的 image-prompt-review 插件需单独安装，本仓库仅保留其规则引用。

Pi Kether Portable

这是一个面向 Windows 11 + WSL2 的安装包，把宿主无关的 Kether/Tifereth 规则和 Pi 执行环境安装到另一台主机，并为所选主代理工具生成接入配置。

安装后得到：

• 通用 Node stdio MCP 入口，以及供 Secure MCP Tunnel 使用的认证 HTTP 入口；Codex 插件可选；
• 通过 get_workflow 按需读取的主代理规则、角色技能和 references；选择 Codex 时另外安装全局规则与技能；
• 普通低级 Agent 使用 openai-codex；Geburah/reviewer 专用 anthropic / claude-sonnet-5，仅允许无工具、无文件访问审查；
• 带 CPU、内存、进程数、输出量、运行时间和写入范围限制的 WSL2/Bubblewrap 沙箱；
• 请求账本、幂等处理、Provider 熔断、审计清洗、结果格式验证、任务队列和监控卡片；
• Python、Java、JavaScript、TypeScript、C#、C/C++、Go、Rust 的 LSP 服务。
• 自有 Pi LSP 适配插件：受管工作代理通过七个 yhwh_lsp_* 工具调用隔离的 multilspy 探针；同一任务内复用未变化文件的服务器，Python 按需保留 Pyright 和 Jedi 两个后端，加速交替查询，空闲或任务结束后回收；C/C++ 和 C# 使用实际退出检查减少清理等待；C# 采用固定单文件 .NET 项目及只读私有进程视图，服务器异常退出时立即报错；Java 采用短任务 JIT 策略、单服务器复用和独立临时索引；旧扩展暂作兼容保留。

安装

一键安装（Windows 11 x64）

构建后的 YHWH-OneClick-0.15.0.zip 包含自包含脚本、校验文件和双击入口。解压后双击 Install-YHWH.cmd，按提示选择允许代理访问的工作目录；直接回车会创建 ~/YHWH-Workspace。也可以只复制单个脚本到目标电脑运行：

powershell.exe -NoProfile -ExecutionPolicy Bypass -File .\Install-YHWH-0.15.0.ps1

默认导出通用 MCP 接入配置，不修改 Codex 全局设置。用 -Hosts "cherry-studio,opencode,deepseek-harness,claude-code" 选择宿主；包含 codex 时才执行原有 Codex 集成。接入文件还需按宿主提示导入，并加载主代理规则；已有配置不会被导出器覆盖。

安装器在 %LOCALAPPDATA%\YHWH 准备固定版本的 PowerShell 7 和 Node，无需预装它们或 Git，也不要求登录 GitHub。工作流源码已嵌入脚本；运行环境和依赖仍需联网下载。Windows 端运行包和 Ubuntu 镜像使用构建时记录的 SHA256 校验，下载内容变化会停止安装，不会自动接受新校验值。

它会导入专用 YHWH WSL2 Ubuntu 24.04 环境，安装 Windows 插件、治理规则和 WSL 沙箱/LSP，再运行安装检查。首次启用 WSL 可能出现 Windows 管理员授权，并需要重启后重新运行脚本；脚本以 3010 表示这一步尚待重启，不会声称安装完成。需要启用硬件虚拟化，且组织策略允许 WSL。WSL 安装方式依据 Microsoft 官方说明。

完成后打开 %LOCALAPPDATA%\YHWH\Open-Pi.cmd，通过 /login 登录下级 worker 所用的 OpenAI 账号；审核代理使用同目录 `Configure-Claude-API