端到端验证：通过 ZCode 的 hook 机制拦截工具调用与权限询问，在浏览器 UI 展示事件流与询问卡片，用户作答后决策回传给 ZCode。
项目本质：对 ZCode 客户端 hook 机制的探索性 PoC。核心目标是搞清楚 hook 能做什么、不能做什么、怎么稳定地做。PoC 聚焦于机制本身，不做任何产品形态设想。
PoC 已验证：
- PermissionRequest 反向控制闭环（Write/Edit/Bash 可被完全接管）
- AskUserQuestion 完全接管（含中文 Other 自定义输入，v2.1.0 端到端实测通过）
所有技术细节都在 docs/ 目录：
| 文档 | 内容 | 适合谁读 |
|---|---|---|
| 01-Hook架构与原理.md | Hook 配置、事件、调用协议、生命周期 | 所有人必读 |
| 02-踩坑记录.md | 9 个关键 bug + 排查流程 | 改 hook 脚本前必读 |
| 03-Schema完整参考.md | 所有 Zod schema + 源码 offset 索引 | 写 hook 返回值时查 |
| 04-AskUserQuestion接管分析.md | ✅ 实测成功：v2.1.0 端到端验证完全接管，含中文 Other 自定义输入 | 后续产品化参考 |
✅ 04 号文档结论已验证（2026-07-22，ZCode v2.1.0）：旧版（v1.x）认为 AskUserQuestion 无法用 hook 接管，根因实际是 PowerShell 5.1 的 4 层编码陷阱（详见 docs/02 坑 9）。修复编码后端到端接管成功。
| 能力 | 状态 | 说明 |
|---|---|---|
| PermissionRequest 接管（Write/Edit/Bash） | ✅ 已验证 | 核心能力 |
| PermissionRequest deny | ✅ 已验证 | exit code 2 |
| PermissionRequest modify（updatedInput 改写命令） | ⏳ 待验证 | schema 已挖到 |
| PreToolUse 拦截 + 通知 | ✅ 已验证 | 含 riskLevel/sideEffectScope |
| PostToolUse 结果展示 | ✅ 已验证 | 含 toolResultPreview |
| AskUserQuestion 接管 | ✅ 已验证（v2.1.0 端到端实测通过） | 用户在浏览器 UI 作答（含中文 Other 自定义输入），ZCode 原生 UI 不弹出。详见 docs/04 §6 |
| AskUserQuestion 通知展示 | ✅ 已实现（随接管能力一并完成） | 作为 UI 渲染层，已支持多选/单选/Other |
zcode-hooks-poc/
├── install.ps1 # 一键安装（备份 config + 注入 hook）
├── uninstall.ps1 # 一键卸载（恢复 config）
├── start.ps1 # 启动总线 + 自动开浏览器
├── hook-dispatch.ps1 # hook 探针（ZCode 调用）
├── bus/
│ └── server.js # Node.js 总线（HTTP + SSE，零依赖）
├── ui/
│ └── index.html # 浏览器 UI（单文件，无构建，用于观察 hook 事件流）
└── docs/
├── 01-Hook架构与原理.md
├── 02-踩坑记录.md
├── 03-Schema完整参考.md
└── 04-AskUserQuestion接管分析.md
cd C:\Projects\zcode-hooks-poc
.\install.ps1必须重启才能加载新的 hook 配置。
# 从开始菜单打开独立的 PowerShell（不是 ZCode 的）
cd C:\Projects\zcode-hooks-poc
.\start.ps1浏览器会自动打开 http://127.0.0.1:7777/，看到"已连接 · 监听中"即成功。
- 切换到 build 或 plan 模式（非 yolo）
- 让 AI 执行写文件操作
- 浏览器弹出黄色询问卡片 + 提示音
- 点击【允许】→ ZCode 原生弹窗自动关闭，工具继续执行
.\uninstall.ps1
# 然后重启 ZCode| 决策点 | 选择 | 原因 |
|---|---|---|
| hook 类型 | process（不是 command） |
避免 cmd.exe 吞引号（坑 4） |
| shell 二进制 | System32\WindowsPowerShell\v1.0\powershell.exe |
避免 WindowsApps symlink（坑 5） |
| PermissionRequest 返回格式 | decision.behavior（不是 permissionDecision） |
Schema 参考 |
| 总线进程 | 独立 PowerShell 窗口 | 不被 ZCode 退出拖累 |
| 绑定地址 | 127.0.0.1 only |
安全红线，外部网络无法访问 |
| hook-dispatch.ps1 编码 | UTF-8 with BOM | PowerShell 5.1 默认 GBK，无 BOM 会让中文注释乱码引发诡异语法错误（坑 8） |
| hook I/O 编码 | 4 层全修（BOM + InputEncoding + WebClient + OutputEncoding） | PowerShell 5.1 默认 GBK，每层都要单独强制 UTF-8（坑 9） |
⚠️ 修改hook-dispatch.ps1注意：必须保存为 UTF-8 with BOM。用 ZCode 的 Write/Edit 工具改这个文件时，工具默认写无 BOM，改完后必须手动补 BOM，否则脚本会运行时静默失败。补 BOM 命令：$c = [System.IO.File]::ReadAllBytes('hook-dispatch.ps1') $enc = New-Object System.Text.UTF8Encoding($true) [System.IO.File]::WriteAllText('hook-dispatch.ps1', $enc.GetString($c), $enc)
- 官方文档（skill）：
~/.zcode/cli/plugins/cache/zcode-plugins-official/zcode-guide/0.1.0/skills/diagnosing-hooks/SKILL.md - 社区讨论：zai-org/feedback#9
⚠️ 重要：社区讨论的部分信息（如"command 支持 args"）与源码不符，以源码反编译为准。详见 02-踩坑记录.md 末尾对比。
- AskUserQuestion 接管：已端到端实测通过（v2.1.0，详见 docs/04 §6）
- 浏览器 UI 不是 Windows 置顶窗口（未来产品化需要时再考虑，PoC 阶段用浏览器足够）
- 总线无开机自启
- 无多会话区分（所有 sessionId 混在一起）
- 无规则引擎（每次询问都必须手动点）
当前 PoC 聚焦于摸清 ZCode hook 机制本身。未来若要基于这条技术路线做实际产品，可能的技术演进方向：
PoC（当前：Hook 机制探索 + 验证）
↓
+ Tauri 桌面壳（置顶窗口、开机自启、独立进程、Win32 原生能力）
↓
+ 多工具适配（CC / CodeX 共用 hook 探针）
↓
+ 规则引擎（"低风险自动允许"等白名单）
↓
+ Cursor / Trae 扩展（IDE 类工具）
↓
+ SQLite 历史持久化 + 回看
桌面框架选型已讨论过：倾向 Tauri（工具优先：低资源占用 + Rust 直调 Win32）。但这属于产品化阶段的决策，不影响当前 PoC。
- ZCode Hook Discussion #9
- ZCode 客户端源码：
C:\Tools\ZCode\resources\glm\zcode.cjs - 官方 hook 示例插件：
hookify、plugin-dev