feat(hooks): 开放用户 http observe hooks 与 Clawd 接入文档

[Cai-Tang-www]

变更摘要

本 PR 以“最小可用、默认安全”为原则，开放用户可配置的 http observe hooks（kind: http + mode: observe），并补齐面向用户的接入文档（含 Clawd 桌宠示例）。

具体改动

1）运行时能力开放（代码）

• 允许 runtime.hooks.items 配置：
  • kind: http
  • mode: observe
• 仍然拒绝 command / prompt / agent，避免能力面误扩张。
• http observe 保持“只观测、不阻断”语义：
  • 禁止 failure_policy=fail_closed
  • 要求 params.url 为绝对 http/https 地址
  • 校验 method / headers 配置合法性
• 新增 HTTP observe 执行 handler：向目标地址发送 JSON 回调（可选携带 metadata）。

2）测试补齐

• 配置层：新增 http/observe 的通过与失败场景校验。
• runtime hooks 类型层：补充 HookKindHTTP 的规范化与验证测试。
• 运行时行为层：补充 HTTP 回调成功与非 2xx 失败路径测试。
• 回归保障：确认 command/prompt/agent 仍被拒绝。

3）文档更新（仓库文档 + 文档站）

• 更新 docs/ 配置与设计文档，明确当前能力边界：
  • 用户 hooks 支持 builtin/sync 与 http/observe
  • 其他 external kinds 暂不支持
• 新增/更新 www/ 用户文档：
  • 中文 Hooks 使用教程（含 http observe）
  • 中文 NeoCode x Clawd 接入实战
  • 英文 Hooks 指南
  • 英文 NeoCode x Clawd 接入示例
• 中英文导航均已接入对应入口。

用户价值

对普通用户

• 用户可通过配置直接把 NeoCode 生命周期状态推送到桌宠/状态看板等本地组件，不需要改源码。

对稳定性

• 在开放可观测能力的同时，不把 hooks 变成通用执行入口。
• 回调链路异常不会阻断主任务执行，降低误伤风险。

对接入效率

• 提供可复制配置与桥接示例，降低第三方组件接入门槛，减少试错成本。

本地验证

已执行并通过以下测试：

• go test ./internal/config -run "RuntimeHooks" -count=1
• go test ./internal/runtime/hooks -run "HookSpecNormalizeAndValidate" -count=1
• go test ./internal/runtime -run "HTTPObserve|ConfigureRuntimeHooksRejectsExternalKind|BuildUserHookSpecAllowsHTTPObserve" -count=1

[chatgpt-codex-connector]

Codex usage limits have been reached for code reviews. Please check with the admins of this repo to increase the limits by adding credits.
Credits must be used to enable repository wide code reviews.

[fennoai]

Found 3 issues worth addressing before merging: one security boundary regression in http/observe, one connection-reuse performance issue, and one documentation gap around what include_metadata actually forwards.

[codecov]

Codecov Report

❌ Patch coverage is 94.09449% with 15 lines in your changes missing coverage. Please review.

Files with missing lines	Patch %	Lines
internal/runtime/user_hooks.go	90.74%	10 Missing and 5 partials ⚠️

📢 Thoughts on this report? Let us know!

[Cai-Tang-www]

已按 review 补充修复，新增提交：fix(hooks): harden http observe metadata and connection reuse。

本次修复点：

1. 安全：include_metadata 默认从 true 改为 false。
2. 安全：即使显式开启 metadata，也会自动剥离 result_content_preview 与 execution_error，避免预览内容/执行错误明文外传。
3. 性能：HTTP observe 成功路径在关闭前补充 drain（读到 EOF），避免频繁重建连接，提升 keep-alive 复用概率。
4. 文档：中英文 hooks 文档与 clawd 接入示例同步更新默认值和安全说明。

回归测试已通过：

• go test ./internal/runtime -run "HTTPObserve|BuildUserHookSpecAllowsHTTPObserve|DrainAndCloseHTTPResponseBody|ConfigureRuntimeHooksRejectsExternalKind" -count=1
• go test ./internal/config -run "RuntimeHooks" -count=1
• go test ./internal/runtime/hooks -run "HookSpecNormalizeAndValidate" -count=1

[Cai-Tang-www]

已补充一轮严格风险修复并推送，提交：c90df738。

对应本轮 review 的处理：

1. 安全（外发风险）

• http observe 端点新增 loopback 限制：仅允许 localhost/127.0.0.1/::1。
• 配置层与 runtime 构建层双重校验，避免绕过。

2. 安全（metadata 泄漏面）

• include_metadata 默认保持 false（此前已改）。
• 即使显式开启，也继续剥离 result_content_preview 和 execution_error。

3. 性能（连接复用）

• 成功路径在 Close 前执行 drain；同时改为有上限 drain（64KiB），避免被大响应拖慢。

4. 语义一致性

• kind=http 的 HookSpec mode 现在映射为 observe，与配置语义一致（不再写成 sync）。

已通过回归：

• go test ./internal/config -run "RuntimeHooks" -count=1
• go test ./internal/runtime/hooks -run "HookSpecNormalizeAndValidate" -count=1
• go test ./internal/runtime -run "HTTPObserve|BuildUserHookSpecAllowsHTTPObserve|BuildUserHookSpecRejectsHTTPObserveRemoteHost|DrainAndCloseHTTPResponseBody|ConfigureRuntimeHooksRejectsExternalKind" -count=1

[Cai-Tang-www]

又做了一轮严格自检（中断风险 / 语义清晰 / 安全兜底 / 注释可维护性），并补了一个小提交：0c67c86c。

本次变更不改行为，只提升可维护性与语义一致性：

• 修正 hooks 相关注释，明确当前支持范围（builtin + http observe）。
• 将 drainAndCloseHTTPResponseBody 注释改为“有上限 drain”，避免实现与注释语义不一致。

回归通过：

• go test ./internal/config -run "RuntimeHooks" -count=1
• go test ./internal/runtime -run "HTTPObserve|RejectsHTTPObserveFailClosedPolicy|BuildUserHookSpecRejectsHTTPObserveRemoteHost" -count=1

[Cai-Tang-www]

/code 帮我提高测试覆盖率，越高越好，然后完成后推送到我的分支

[fennoai]

完成情况

已补充并推送测试覆盖率提升提交 d60db6e2 到当前 PR 分支 Cai-Tang-www:feat/issue-586-web-ui-polish。

本次补测

• internal/config/runtime_hooks_test.go
  • 覆盖 http observe 的 localhost / ::1 合法场景
  • 覆盖非法 URL、非法 headers、空 header 名和值等失败分支
  • 覆盖 loopback 与参数读取辅助函数分支
• internal/runtime/user_hooks_test.go
  • 覆盖 repo http observe spec 构建
  • 覆盖 runtime 装配兜底校验的多种拒绝分支
  • 覆盖 http observe 的请求失败、空错误体、JSON marshal 失败、布尔参数解析分支
  • 覆盖 symlink escape 的路径拒绝分支

验证结果

• go test ./internal/config -coverprofile=/tmp/config.cover.out
• go test ./internal/runtime -coverprofile=/tmp/runtime.cover.out
• go test ./internal/runtime/hooks -coverprofile=/tmp/hooks.cover.out
• go test ./...

关键新增逻辑的函数覆盖率已明显提高，例如：

• internal/config/runtime_hooks.go
  • validateRuntimeHTTPObserveItem: 67.9% -> 100.0%
  • isRuntimeHookHTTPObserveLoopbackHost: 71.4% -> 100.0%
• internal/runtime/user_hooks.go
  • validateConfiguredHookItemForP6Lite: 83.3% -> 100.0%
  • buildHTTPObserveHeaders: 77.8% -> 100.0%
  • sanitizeHTTPObserveMetadata: 88.9% -> 100.0%
  • drainAndCloseHTTPResponseBody: 75.0% -> 100.0%

View job run