[Hooks RFC #679] Task DX: hook lint / dry-run / trace CLI

[Cai-Tang-www]

父 RFC: #679

背景

原 RFC Phase 3 三个工具(lint / dry-run / trace)合并实现,共享 CLI 子命令组与 fixture 体系。当前 hook 开发只能"上线后看日志",门槛过高。

目标

在 neocode CLI 下提供 hook 子命令组,覆盖配置静态校验、模拟执行、运行时追踪三种场景。

范围

1. `neocode hook lint [path]`

• 默认扫描 ~/.neocode/config.yaml runtime.hooks 与 <workspace>/.neocode/hooks.yaml
• 校验项:
  • point/mode/failure policy/kind 兼容性(复用 #Task-A 的能力查询)
  • params schema 与必填项
  • matcher DSL 合法性(依赖 #Task-Matcher)
  • http observe URL loopback 约束
  • command kind argv 安全约束(依赖 #Task-Command)
• 输出:文件 + 行号定位 + fix hint

2. `neocode hook dry-run --hook= --fixture=`

• fixture 文件:YAML/JSON,基于 hook-payload.v1 schema (依赖 #Task-Schema)
• 模拟构造 HookContext,执行单个 hook,打印 RunOutput
• 输出:status / block / annotations / duration
• 不接入真实 runtime,只走 hooks 包

3. `neocode hook trace --run-id=` 或运行时 --trace-hooks flag

• 订阅 hook_started / hook_finished / hook_failed / hook_blocked 事件
• 按 run 聚合,时序输出 + 耗时直方图
• 同时支持读取历史 run 日志(若 runtime 写盘)

实装

• internal/cli/hook_command.go (新)
• 复用 internal/runtime/hooks 与 internal/config 已有 API,不引入新依赖
• fixture 解析放 internal/runtime/hooks/fixture/

验收

• 三个子命令均有 --help、退出码语义清晰
• lint 在 8 种典型配置错误上有 golden test 输出
• dry-run 对 3 个内置 handler 全部跑通
• trace 在 e2e 测试中能完整复现一次 before_tool_call 时序
• 文档:docs/guides/hooks-cli.md

依赖

• #Task-A (能力查询)
• #Task-Schema (fixture 格式)
• 强烈建议在 #Task-Matcher / #Task-Command 落地后再补完 lint 规则

不在本任务范围

• TUI 内嵌的 hook 调试面板
• 远程 trace 上报