项目可观测、诊断与部署闭环
实践 / 建议工程化与可观测：把可靠步骤交给确定性执行器
每个项目应交付可观测入口、Grafana 关联、debug/deploy 技能及指南，并配套验证与恢复能力。 下文先说明通用工程接口，再以 IDP/Egress 最新本地快照展开项目能力包和可自主执行的闭环。
统一语义，保留各技术栈命令
| 能力 | 契约 | 常见陷阱 |
|---|---|---|
| format/fix | 可修改文件，输出差异 | 修正后仍沿用修改前 SHA 的验证 |
| lint/check | 默认只读检查，范围与规则可追溯 | 把 --fix 隐藏在 lint 中 |
| test | 指定套件，环境/数据可准备与清理 | 多任务写同一数据库或 Maven target |
| verify | 汇总必需项与报告，明确最终判定 | 文档称“等价 CI”，脚本实际漏掉证据检查 |
| observe | 默认读取日志、指标、版本与覆盖 | 查询失败当作无异常 |
适配记录 command、cwd、工具版本、超时、资源需求、报告和副作用。 底层可用 Maven/Gradle、Node、Go 或移动端工具，不要求所有项目使用 pnpm。 像必需检查、push 结果确认、报告解析、去重、预算、状态转换应由代码保证； 模型集中处理调查、设计与实现中不能预先穷举的部分。
共享测试环境必须解决竞争
Golden Path 当前方案用发布状态和最近窗口判断占用、最多等待 30 分钟； 这种“先查再用”存在同时抢占窗口。先复用发布系统原子队列/预约能力，缺失时再补执行入口。 推荐租约覆盖构建/部署/业务测试所需范围，带有效期、持有者、释放及过期恢复。 发布前后和业务测试前后核对实际制品；发现被覆盖，报告环境漂移并重验。
默认 L1 的发布成功、Ready/期望 commit/无重启、前后错误日志对比、健康接口， 只能证明对应部署检查；健康接口未配时注明 skip，业务 验收标准 另验。 “未验证发布”必须保留为缺口；共享环境通过后保留分支制品、仅 Pod 未 Ready 回滚等当前方案行为， 要在接入卡写明，不能让下一个任务误把遗留分支当环境基线。
应用可观测与 Agent 过程可观测
应用侧：记录服务/环境/制品版本、请求与业务关联、错误分类、延迟、资源与队列行为。 指标 label 控制基数，高维请求/任务细节放日志与受控 trace；跨 FWD 链路未贯通时明确断点。 IDP 已有指标命名、桶和 label 检查，字典仍要随 MR 维护；Egress 部分告警阈值待校准。
流程侧：贯通 GitLab Issue、Multica Issue/topic/reply、run、仓库 SHA、制品、验证报告、MR、部署、故障的关联 ID。 将耗时拆成排队、环境准备、模型、工具、构建、验证、人工等待； 把失败区分为知识错、技能错、代码错、环境错、权限拒绝、预算耗尽、版本漂移和人工拒绝。 否则“Agent 很慢/不可靠”无法定位到可改进的工程环节。
长任务恢复借鉴持久进展清单与 Git 历史；进度必须由证据支持。 日志保存必要操作轨迹和结果即可，不依赖模型隐藏推理，也不把敏感原始资料塞进公开知识页。
每个项目的可观测与操作能力包
目标是让 Agent 能在明确的环境与授权范围内，自行观察、诊断、处理并验证实际效果。 每个项目都应有可观测入口、Grafana 看板关联、诊断指南与技能、部署指南与技能，以及验证和恢复方法。 这应成为项目接入自主工作流的交付要求，并纳入功能变更的完成定义。
本节以两个本地工程的新快照为依据：IDP 00b8ecb053c5d33a743ba17a93bcfb4ac30187f4、
Egress 57022539d795424c74a0d99a0c5a7af2ad7cb135；读取时均无未提交修改。
已核对文档、技能、部分脚本与 CI 定义，未执行部署、线上查询、看板写入或本轮业务测试。
本节的新快照补充前文历史调研，不代表已重新验收全部旧结论。
两个参考工程已经做了什么
| 能力 | fs-developer-platform | fs-egress-proxy | 可推广的组织方式 |
|---|---|---|---|
| 项目入口 | docs/observability/README.md 做一页索引；AGENTS.md 路由到 debug、指标和技能 |
debug/deploy 技能关联调试指南与监控说明 | 根入口指向唯一正文，按问题加载，避免复制多份命令 |
| 观察与诊断 | 应用日志、Prometheus、Grafana、Pyroscope、Pod 启动日志及专用排查技能 | Pod/stdout/落盘日志、Prometheus、Grafana 与 HTTP/SOCKS/FWD 路径诊断 | 指标发现趋势，日志/调用链/性能证据解释机制，缺口明确记录 |
| 看板资产 | 两环境快照，共用 idp-developer-platform-metrics UID；面板定义对应，数据源/默认变量适配环境 |
生成两环境产物，UID 为 egress-overview；指标、网络、目标分析和日志联动 |
看板及查询口径跟代码版本维护，环境映射明确 |
| 工程校验 | check:metrics 接入检查链；指标字典仍需人工与代码同步 |
grafana:test 组合 Python 看板和 Node 同步测试；CI 有同步契约测试依赖 |
验证查询和同步行为，不能仅检查 JSON 能解析 |
| 部署路径 | deploy:release 驱动 tag、build 与目标任务触发，指南要求 stage 与 API 验证后再继续 |
deploy 技能限定 Firstshare，核对流程、镜像、运行版本、协议路径和采集 | 显式环境、固定版本、发布后真实验证；等待与失败分支由可检验的流程保障 |
| 能力边界 | 自用观测面与对租户开放的 Grafana/PromQL 查询能力分开 | debug 默认只读；变更转 deploy 或明确授权的流程 | 诊断能力、写权限与任务授权分别登记 |
这些是当前仓内资产和实现证据，不等于两个服务此刻所有看板、采集、告警与发布链路都已线上验收。
名为 feeds/grafana 的治理仓与这里的运行看板是不同职责：前者的发布治理经验可以复用，
不能仅凭仓名推断已经提供各项目的观测能力。
每个项目必须能回答的七个问题
| 编号 | 必备内容 | Agent 要能完成什么 | 接入验收方式 |
|---|---|---|---|
| 1 | 身份与环境映射 | 从 repo/服务定位应用、profile、集群/命名空间、制品与实际运行版本 | 在指定环境解析目标并与运行事实核对，发现多候选不猜测 |
| 2 | 可观测总览与 Grafana 入口 | 找到看板 UID、实例、数据源、变量、指标字典、日志和可用调用链 | 能打开对应视图，也能执行有范围的查询并解释结果 |
| 3 | 诊断指南与 debug 能力 | 按症状选择证据、复现、建立假设和反证，定位受影响路径 | 用已知故障样例检验诊断；证据不足时给出缺口而非编造根因 |
| 4 | 部署指南与 deploy 能力 | 计划、准备制品、申请环境占用、发布、等待终态、核对版本 | 对固定候选在授权测试环境执行并留下真实发布记录 |
| 5 | 业务与工程验证 | 执行分层测试、关键旅程、发布前后对比及必要的长时间稳定性测试 | 明确验证范围、覆盖、结果和未执行项；假绿样例能被拦截 |
| 6 | 恢复与接管 | 暂停、释放租约、定位可用旧制品；按条件回退或前向修复 | 演练失败、超时与环境漂移，不以盲目重试或重启代替判断 |
| 7 | 记录与知识回流 | 将过程、发布事实、验收证据与需求关联，并提出长期改进 | GitLab 可追溯到 Multica、实际报告和版本；结论审定后进入知识/测试/技能 |
要求落实到业务项目与实际运行单元，不等于 500 个 Git 仓都要独立建一个空看板或复制部署脚本。 共享库关联消费服务和制品兼容验证；纯文档仓登记不适用及理由；跨仓业务项目维护聚合视图和服务子视图。 Web/移动端关联前端错误、性能、版本分布、关键旅程和后端依赖，发布能力按站点或包渠道适配。 长时间离线的客户端要说明数据延迟，不能把“暂未收到错误”解释为全量正常。
Grafana 要让人看得懂，也让机器查得准
Grafana 是观察入口之一。Agent 应优先通过已有受控 CLI/API 获取面板定义和结构化查询结果， 截图用于确认展示、交互与辅助留证；不把截图识别作为唯一的数值或故障判断依据。
每个看板关联应登记实例/profile、UID、数据源身份、环境/应用/集群/Pod 等变量、 时间范围、采样步长、时区、指标单位、分母、数据新鲜度与缺数语义。 模板变量必须展开并核对目标，不能只给一个 URL 就认为 Agent 已具备可观察能力。 下钻日志、调用链和火焰图时保留同一目标与时间窗口，但只有可靠关联 ID 才能声明属于同一请求。
| 看板内容 | 机器应理解的语义 | 典型误判 |
|---|---|---|
| 版本与采集状态 | 当前制品、配置版本、采集时间、新旧 Pod 覆盖 | exporter 存活等于应用业务正常 |
| 用户体验与关键业务 | 可用性、延迟、成功率、业务完成量及明确分母 | HTTP 200、消息投递成功等于最终业务成功 |
| 依赖与资源 | 数据库/缓存/消息、线程/连接池、JVM/GC/堆外内存、反压 | 单个峰值就判泄漏；不同内存口径直接相加 |
| 变更与诊断 | 发布标记、错误分类、日志/trace/profile 下钻 | 时间接近就认定同一根因；发布后暂时零错误就关单 |
| 观测系统自身 | 采集缺失、查询失败、队列丢弃、延迟和覆盖 | 无数据当作 0，零流量当作 100% 成功 |
阈值由项目依据业务目标和历史基线确定。通用模板可以提供结构和待校准项，不能替团队定义全部 SLO。 观察窗口应覆盖相应机制并有代表性流量；数据不足时保持 unknown，自动处理流程据此补采集或升级。 新版本增加/更名信号时，同一变更评审中检查字典、查询、面板、告警与排障指南的影响。
技能、指南和脚本各自承载什么
| 层次 | 内容与落点 |
|---|---|
| 公司层 | ai-wiki 定义观测、证据、权限与验收底线；fs-ai-hub/TeamAI 发布通用能力和版本 |
| 团队/领域层 | 维护领域症状、业务不变量、共有依赖、标准面板及已校准的团队规则 |
| 项目层 | 指标与查询、看板源码、环境映射、诊断/部署指南、适配脚本与项目测试，跟随代码版本 |
| 运行层 | Multica 选择已锁定的能力与项目配置，保存执行过程；GitLab 保存合同、进展和验收证据 |
建议项目入口关联 docs/observability/README.md、docs/guidelines/debug.md、部署指南，
以及现有 .agents/skills/debug、.agents/skills/deploy 或等价能力入口。
不强制迁移成熟项目的目录，只要求统一发现机制；AGENTS.md 做路由，不重复粘贴长指南。
Skill 负责何时使用、输入、步骤、权限、停止条件和证据；指南解释项目机制和诊断方法； 脚本负责参数校验、幂等、等待、超时、状态机、结果采集和明确失败。 debug/deploy 不是仅有一段 Prompt：它们应有可调用入口、真实工具能力、失败语义和最小验证。 跨项目通用脚本保持唯一维护源，项目记录适配与固定版本，避免每仓复制后各自漂移。
以下是建议登记字段，不是现有平台已支持的 API 或必须采用的新文件格式；可映射到项目目录或已有配置：
schema_version: 1
project_id: example-service
team: paas
domains: [permission]
runtime_targets_ref: project-catalog/environment-map
observability:
guide: docs/observability/README.md
dashboard_refs: [project-catalog/dashboard-map]
query_catalog_ref: project-catalog/query-map
capabilities:
observe: project-catalog/observe-binding
debug: project-catalog/debug-binding
deploy_test: project-catalog/deploy-test-binding
verify: project-catalog/verify-binding
recover: project-catalog/recover-binding
execution_policy_ref: project-catalog/approved-policy
引用必须能解析到具体版本、执行器、参数约束和环境范围，不能只有不可执行的占位名称。 凭据通过运行平台注入，登记表只保存身份和访问范围引用。Agent 的生产观察权限与部署权限分开。 静态文档可被代码查询索引，但当前环境、版本与故障结论须核对实时事实；不会因知识库写着正常就跳过观察。
一条可自主执行的端到端路径
- 发现与对齐目标。 人提出需求或诸葛发现异常，确认服务、环境、版本、影响、验收标准和授权。
- 建立观察基线。 固定时间窗读取看板查询与原始信号，检查采集覆盖、流量与数据新鲜度。
- 诊断并选择处理类型。 结合代码/日志/指标建立机制解释和反证；代码、配置、容量、数据分别路由。
- 实现并自验。 开发 Agent 在隔离工作区修复，运行相关分层测试，记录新旧行为与固定 SHA。
- 发布测试环境。 在已授权范围内解析目标、占用环境、准备制品、调用部署技能并等待最终结果。
- 独立验证与继续观察。 核对实际版本和配置，运行关键业务旅程，对照发布前后信号与故障症状。
- 处理失败或交付。 可安全重试的步骤按预算重试；结果不明先对账；回退须满足授权和数据兼容条件。 验证通过后形成可审阅 MR，生产推进按项目已确认的发布政策及必要人工门执行。
- 观察真实效果并回流。 发布后按真实流量、观察窗口和恢复标准判断，分别记录开发完成、发布与恢复。
Agent 可以在这些步骤间自主推进；范围变化、证据不足、结果不明、重大风险和超出授权时进入明确的接管出口。 “自主处理”不表示重启、删除 Pod、改配置或重放数据都自动获得许可，也不表示每一步都要人重复确认。 通过预先批准的项目政策定义正常路径、停止条件和人工决策点，减少临时判断和反复询问。
本次核对发现的差异与改进点
发布触发、门禁通过和运行恢复要分开
IDP 的 deploy 技能明确要求先 stage、等待 API smoke/critical-path 成功后继续。
读取 deploy.mjs 可见它在部署入口核对 build/check 结果，然后触发选中的 manual job；
触发函数不等待部署结束，入口没有将 stage API 结果加入通用 gateJobs。
因此不能把 driver 返回成功当作全流程完成，应由受控编排/CI 校验下一阶段前置条件并等待终态。
CI 注释还记录了 migration 与 stage API 验证依赖顺序的缺口，涉及数据迁移时须验证实际依赖。
本轮没有验证线上 pipeline 与 GitLab 服务端保护，不能据此断言所有路径一定能够绕过门禁。
Egress 的 debug/deploy 技能限定 Firstshare，诊断只读，发布后检查运行镜像、协议路径及双抓取 job。 这些限定适合做测试环境自主闭环的起点，但不能自动外推为生产部署能力。 文档中的固定容量/预算期望值也要与当前制品、配置对应，不能原样复制为所有版本的判断标准。
同名同步命令存在不同副作用
IDP grafana:sync fetch 会覆盖本地快照，push 使用 overwrite: true。
Egress 的 fetch 写临时文件，push 校验目标数据源、保存旧看板、带版本并使用 overwrite: false，
写入后回读比对；Node 同步契约测试已在 CI 中被依赖。
两者不能用同一个“同步成功”假设来解释，Agent 调用前要解析具体项目的操作契约。
建议推广 Egress 的明确环境、先比较、备份、版本冲突停止和回读校验机制；
看板写入作为独立变更能力管理，运行时观察不需要看板编辑权限。
Egress 的 CI job 名为 grafana-sync，本次读到的执行内容是同步契约测试，不能说 CI 已自动推送线上看板。
告警仍存在待校准模板，仓内配置存在不等于线上已经启用。
项目策略差异必须登记
新读到的 IDP AGENTS.md 含符合条件后自动完成 MR 审查/合并的项目约定，
其 deploy 技能也描述了经确认后由 Agent 调用发布驱动的路径；这与本报告前述公司人工门基线存在范围差异。
应在项目政策中明确适用条件、授权来源及必要的人审点，不能把公司基线误写成所有项目的当前实现，
也不能把某仓约定直接扩大为其他团队的授权。本报告中的通用泳道仍表示建议基线，项目可按批准的政策适配。
Sonar 扫描同样要看实际配置：新读到的 IDP CI 中，普通 MR 的相关扫描可以是 manual 且允许失败， 满足特定变量/配置变更等条件时才自动运行；不能只因 CI 含扫描 job 就认定每次 MR 都有阻断扫描。 因此项目信息应登记必需项、条件项和可选项，报告按真实执行结果判定。
观测失效不应拖垮业务，但应停止无证据的自动放行
本次通过 code-search 核对公司现行“观测代码不得阻断业务”规则：观测采集走旁路、隔离异常、 异步且有超时/容量限制，初始化失败不能破坏主业务；业务自身错误仍按业务语义处理。 需要同时处理两种后果：业务可以继续服务；缺少关键观察证据的自动发布/恢复判断不能继续宣称通过。 按规则对观测代码改动验证断网、屏蔽观测域名、观测端 500 等场景，记录业务表现与采集降级。
接入验收与推广顺序
把以下检查加入项目接入验收，先在 IDP/Egress 的授权测试环境试点，再推广到 Java 业务工程：
- 新 runtime 能根据项目入口找到看板、查询、debug/deploy 指南与固定技能版本，实际读取权限有效。
- 给定服务与环境，正确核对应用、Pod、版本、数据源和模板变量；错误环境映射会被拒绝。
- 数据源无权限、无序列、零流量、采集延迟和错误查询分别产生可识别结果，不被合并为“正常”。
- 对代表性缺陷完成取证、修复、自验、测试环境部署和业务验证，证据绑定相同交付版本。
- 部署超时、结果不明或 API 验证失败会阻止后续阶段；重新进入时先对账，避免重复副作用。
- 验证期间版本被其他任务覆盖时标记环境漂移；已批准的恢复流程可执行并核对结果。
- 看板查询失效、同步冲突或指标口径变更有检查与责任人；改观测本身不会阻断业务。
- GitLab 与 Multica 记录能让另一位人或 Agent 恢复工作，讲清已证明、未证明与需要谁决定的事项。
组织上可先发布一个公司通用能力包，加项目适配和验证样例；不要要求所有项目一次性重写平台。 发布成功率、诊断证据完整性、错误通过、环境漂移、恢复时间和人工接管负担共同衡量效果， 不以“创建多少看板、安装多少技能”作为端到端能力已经形成的证明。
固定版本参考
IDP 指标字典中的 L0–L4、既有 CI job 名含 _0_ 等沿用原系统标识以保持兼容；
本节新提的步骤和验收项均从 1 开始。上述源文件可能继续变化，实际接入前按目标版本再次核验。
本节依据： IDP 指标检查、观测规范、Egress 监控说明。