From 588f764340c63932da504cad36f12aabb9a4a2a1 Mon Sep 17 00:00:00 2001 From: Codex Date: Mon, 1 Jun 2026 14:06:03 +0000 Subject: [PATCH] docs: clarify observability boundary --- AGENTS.md | 1 + docs/reference/observability.md | 8 ++++++++ 2 files changed, 9 insertions(+) diff --git a/AGENTS.md b/AGENTS.md index a62af560..af06651c 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -6,6 +6,7 @@ UniDesk 是一个以主 server 为统一入口的分布式工作平台；本文 - P0: 可见性问题是所有任务的优先级最高基础设施问题；无论当前正在开发、发布、排障、写文档、跑 CI/CD 还是做远端透传，只要遇到会遮蔽状态、耗时、失败原因、任务进度、日志尾部、trace、命令结果或关键证据的可见性缺口，必须先修复可见性再继续原任务，避免后续反复踩坑和浪费时间。 - P0: 可见性修复优先采用低摩擦、短反馈、可复用的 CLI/日志/状态输出改进；不得把不可见问题包装成临时人工记忆、长日志全量 dump、重复大回环 CI/CD 试错或额外旧门禁。 +- P0: 可见性、trace、诊断文案和降级原因只能作为定位与验收证据，不能替代缺失能力实现或未修复功能；发现能力缺失就补能力，发现功能未修复就修功能本身，细则见 `docs/reference/observability.md`。 - P0: check、smoke、layout、trace 或 CI/CD 观测命令因仓库声明依赖缺失而跳过、降级或不可见时，直接按该 repo 的锁文件和包管理器安装依赖后继续验证；禁止把缺依赖的 skip 当作有效结果，也不要绕到人工猜测、旧门禁豁免或重复大回环试错。 ## P0 最高优先级：最新要求与旧门禁清除 diff --git a/docs/reference/observability.md b/docs/reference/observability.md index bbe9ea65..12955941 100644 --- a/docs/reference/observability.md +++ b/docs/reference/observability.md @@ -2,6 +2,14 @@ UniDesk 的可观测性优先级高于静默成功。CLI、服务日志、Docker 日志和数据库状态都必须能通过短命令查询。 +## Capability Boundary + +可观测性是定位、验收和排障手段，不是功能完成标准。Trace、日志、诊断文案、fallback 标记、只读原因、降级提示和 issue 进展只能说明系统在哪里失败、为什么失败、修复后如何验证；它们不能把缺失能力包装成已完成，也不能把未修复功能包装成可接受状态。 + +当证据表明某条用户路径需要的能力不存在、没有真正接入、没有复用预期资源、没有返回最终业务结果，或仍停留在 mock、fixture、fallback、只读替代和提示文案时，正确动作是补齐能力或修复功能本身。允许先补最小观测来定位根因，但完成条件必须回到原始用户入口的真实行为闭环，并证明能力已经可用。 + +因此，CLI、Web、trace 和 issue 评论中的状态字段必须避免把“已观测到缺口”“已显示失败原因”“已提供诊断入口”表达成“问题已解决”。如果当前阶段只能增加可见性，输出应明确标记为诊断进展或阻塞定位；不得关闭对应功能 issue，不得把观测增强当作验收通过。 + ## CLI Logs 异步 job 的 stdout 和 stderr 位于 `.state/jobs/`。`job list` 默认只返回最新 50 条摘要，并为已知异步工作流返回轻量 `progress.summary`；`job status` 会返回结构化 `progress` 与有限尾部，避免输出爆炸，同时保留完整日志文件路径便于继续排查。实现必须只读取日志尾部字节，不得先把完整 job 日志读入 CLI 内存；长时命令的阶段、关键对象名和下一步查询命令应优先沉淀到 `progress`，不能要求调用者先阅读完整日志才能知道是否卡在提交、构建、发布或观测阶段。