[EASYGOING45]

新增 bk-cli monitor <module> <tool_name>，通过现有 context 与用户凭据查询日志、指标、告警、APM/Trace 等观测数据。提供 11 个模块、65 个只读业务工具，每个命令直接请求对应的网关 HTTP API，复用公共请求执行和最终结果输出。

实现与评审修复

• 为 65 个业务工具声明独立 HTTP 路由、方法、参数位置和鉴权配置（40 个 POST、25 个 GET）；发现、Schema 与权限辅助命令使用各自的诊断 API。
• 复用公共 --stage、重复 --header 和 --jq 契约；业务及中间请求均使用最终调用选项，不改变 active context。结果与 Profile 来源信息经过共享输出流程，投影失败不重发请求。
• 支持 V1/V2 Profile、可读时间、日志过滤与上下文定位。V2 预检检查工具预设覆盖后的最终资源；无法验证资源时保留 permission_only，预检不执行 SQL。
• 告警列表和 TopN 根据最终业务生成原生 bk_biz_ids，本地拒绝冲突输入；归属不符或无法验证的告警列表不会进入最终输出。区分告警不存在、API 不存在、部分失败和服务端失败。
• 兼容旧版权限 API 缺少 state 的响应：必须由服务端 Schema 明确声明业务权限，且唯一工具、Action、业务和授权结论一致。拒绝缺失、冲突或重复的授权响应，不从本地目录推断权限。
• 增加 relation_route_unavailable 和 response_too_large 分类及处理提示；通用 503 不再被描述为权限拒绝。匹配上游错误仅用于选择固定错误码，不回显原始错误文本。
• SQL 资源发现前置工具改为 list_result_tables，文档明确区分 BkBase 结果表与时序分组表；预检通过不代表查询或平台表归属校验成功。
• 同步 monitor Skill 与通用部署示例，增加权限兼容回归及独立集成用例。保留原有更新器错误路径测试，不修改其运行时代码或降低覆盖率门槛。

本地验证

以下结果对应提交 45d7241e5837c9788778c3849a9fa9ec89fb3a71 的文件内容；使用干净源码副本和合成服务验证。

检查	结果
go test ./... -count=1	27 个测试包通过
monitor、monitorapi、output 的 go test -race	3 个包通过
完整 Docker mock 集成回归	153/153，通过；含 14 个 monitor 场景
MONITOR-014 按场景 ID、精确文件路径独立运行	均通过；权限预检不执行 SQL
make fmt、make lint、make build、git diff --check	通过；lint 为 0 issues
提交历史、暂存内容和源码凭据扫描	未发现真实凭据；源码扫描的 3 处上游命中为测试占位值或请求 ID 示例
公开内容审查	使用虚构业务 ID 与通用部署示例；未附生产配置、业务响应或受控验收附件

验证边界

• 上述集成回归使用合成服务，不等于 65 个工具已在所有真实部署中完成验收。
• 本次 CLI 修复不包含服务端返回语义、存储路由、数据接入或结果表归属校验的修复；未完成真实 SQL 查询成功路径及日志提取成功路径的验收。
• 真实缺权限账号、跨租户、异构部署来源和服务端审计一致性仍需专项验收。

本 PR 申请代码评审，不包含自动合并、部署或版本发布。

使用入口：Profile 初始化、monitor Skill。

[wklken]

@robot-wklken 你也 review 下

[robot-wklken]

@EASYGOING45 基于最新拉取的 d320f0059b737d9ea0f604cf7f2f1be6eb35cafc 审查，merge base 为官方 master@ee4d3eb74e8e70fc233af0b03fb524c020426fe3。这次变更涉及 64 个文件、约 1.24 万行，以下为风险优先审查，未逐行穷尽全部工具目录与文档。

确认了三个需要修复的问题，均为【新】、中等严重程度（P2）：

1. 观测工具缺少公共 --jq 契约。 cmd/system/monitor/tool_command.go:65 没有注册 output.AddJQFlag；cmd/system/monitor/profile_runtime.go:178 又直接编码输出，绕过 output.WriteCommandEnvelope。实际执行 bk-cli monitor log search_logs --jq '.data' 返回 unknown flag: --jq，与 AGENTS 的最终结果投影要求及 user-guide 的“所有 system action”说明冲突。能否在观测 action 上补齐 flag，并让最终结果（含 Profile 信息）经过共享投影路径，覆盖正常结果、dry-run 和投影失败的测试？仅注册 flag 仍不足以实际执行投影。

2. 无法覆盖请求 stage 和 headers。 cmd/system/monitor/tool_command.go:85 只单独注册 body；cmd/system/internal/unifiedmcp/client.go:124 构造 RequestSpec 时没有传入 Stage / Headers。实际命令加 --stage test 或 --header 'X-Example:probe' 均返回 unknown flag。空 Stage 在共享 URL 构造中固定落到 prod，context 配置也没有独立 stage 字段，因此配置一个 context 不能替代 stage 覆盖；单次租户/header 覆盖同样不可用。能否复用公共 flag 约定，并将这些值传给本次调用及 permission/profile 的中间请求，补上 URL 与 header 传递测试？

3. V2 Profile 的元数据预检检查公共默认表，而不是当前工具覆盖后的表。 cmd/system/monitor/profile_v2_check.go:132–142 切换到 list_time_series_metrics 后重新 activateBinding，导致 tools.execute_sql_query.table_id 被丢弃。例如公共 args.table_id: existing.table，单工具预设 execute_sql_query: {table_id: missing.table, sql: 'SELECT 1'}：受控 mock 中 profile check 对 existing.table 发出元数据请求，退出 0 并报告 validation: metadata；随后相同 Profile 的 SQL 请求使用 missing.table，返回 resource_not_found。这不是要求预检验证 SQL 表达式，而是它连已经解析出的目标表都检查错了。能否从原工具最终解析参数取得 table_id，并保证元数据请求检查同一资源；若无法检查，则明确保留 permission_only？能否补一例工具预设覆盖公共资源的回归测试？

关键调用链证据：

问题	代码位置	参数/结果产生处	消费处	确认程度
jq 未接入	tool_command.go:65、profile_runtime.go:178	newToolCmd / writeMonitorEnvelope	Cobra flag 解析 / 最终输出	实际 CLI 复现
stage/header 未传递	tool_command.go:85、unifiedmcp/client.go:124	monitor 构造器 / Call	requestexec.executeRequest / api.BuildURL	实际 CLI 复现及静态链路
预检资源漂移	profile_v2.go:267、profile_v2_check.go:132	bindingArgs 中精确工具覆盖	元数据请求 / SQL 请求	mock 捕获请求确认

已核对维护者此前的七条 inline 意见：MCP facade 接入方式仍然存在，实际链路是 newToolCmd → unifiedmcp.Execute → Call → POST /mcp/execute_tool/，不是调用各工具底层 API；README、公共 user-guide/design 中的 monitor 内容和 proposal 文件也仍在当前 diff 中。这些属于已提出的接入方式/文档归属意见，未当作新增运行时缺陷重复计数。历史 PR23 的 body 文件/stdin 问题在此版本未复现；当前实现两条路径均成功，精确日志定位整数也正常。

验证：本次 go test ./... -count=1 的 27 个有测试包全部通过，go build、monitor/unifiedmcp 的 go vet、git diff --check 通过；三个 flag 和预检表漂移由独立本地 CLI/mock 探针复现。工作树未修改。make lint、make test 未运行（本工作树缺少对应 bin 工具；测试采用上述 Go fallback），Docker 集成、race、coverage 和真实服务验收未复跑，不能据此背书 PR 正文中的这些结果。Robert heartbeat 包装器两次在启动测试前因数据库锁失败，随后直接执行 Go 测试取得结果。

建议：merge after fixes；同时与维护者落实已提出的接口接入方式意见。

[from-codex local repo]

[wklken]

@EASYGOING45 抽空看下review comments。 需要线下讨论可以单独找下我

[EASYGOING45]

收到,我这边Review处理一下哈

[EASYGOING45]

本次评审意见已在提交 1fbe628 中修复并推送：

• 65 个业务工具改为逐工具直连 API，移除通用执行入口。
• 补齐 --jq 输出投影，以及 --stage、--header 向业务请求和中间请求的传递。
• 修复 Profile V2 预检目标与工具最终参数不一致的问题。
• 按建议收敛文档：使用说明集中到 monitor Skill，docs/monitor.md 保留 Profile 初始化说明；恢复公共文档，移除 proposal。

本地验证结果：27 个 Go 测试包、151/151 集成场景通过；相关 race、覆盖率门禁、格式、lint、vet 和构建检查通过，并新增了上述问题的回归用例。

[tencentblueking-adm]

All committers have signed the CLA.