diff --git a/.agents/skills/unidesk-cicd/references/control-plane.md b/.agents/skills/unidesk-cicd/references/control-plane.md index 0683b113..bd7acc02 100644 --- a/.agents/skills/unidesk-cicd/references/control-plane.md +++ b/.agents/skills/unidesk-cicd/references/control-plane.md @@ -2,6 +2,8 @@ 控制面负责 PipelineRun、RBAC/Pipeline/Argo、node-scoped runtime lane 和 D601 节点本地 infra bootstrap。正式入口都必须使用 `bun scripts/cli.ts`，不要把裸 `kubectl`、`argo` 或 `tkn` 当长期操作面。 +微服务契约版本、source/runtime commit、镜像 provenance 或部署对齐检查只能显示非阻塞 warning，不得成为线上用户业务、admission、dispatch、readiness 或 CI/CD public gate。控制面仍可报告 drift 并引导修复，但业务健康与用户入口成功证据不因 drift 被改写。 + ## G14 legacy Control Plane 本节 `trigger-current` 只适用于 YAML 明确解析为 legacy/manual authority 的 G14 lane。 diff --git a/.agents/skills/unidesk-code-queue/SKILL.md b/.agents/skills/unidesk-code-queue/SKILL.md index ba6f12cb..2b8780fe 100644 --- a/.agents/skills/unidesk-code-queue/SKILL.md +++ b/.agents/skills/unidesk-code-queue/SKILL.md @@ -29,6 +29,7 @@ AipodSpec/Artificer、task manifest 和 queue 渐进披露见 [references/resour ## P0 边界 +- AgentRun 与调用方之间的契约版本、源码/镜像版本和 `commitId` 对齐只能产生非阻塞 warning；可安全归一化的请求继续 admission/dispatch，不得因版本或契约漂移阻止用户任务、session、run、command 或 runner。 - 新写入口不要用 `codex submit/steer/resume`；这些 legacy mutation 已冻结。 - Artificer task prompt 只引用 task 自身的 primary workspace： - 默认写当前工作区 `.`，需要子目录时写相对路径； diff --git a/.agents/skills/unidesk-otel/SKILL.md b/.agents/skills/unidesk-otel/SKILL.md index 1525533f..4889518d 100644 --- a/.agents/skills/unidesk-otel/SKILL.md +++ b/.agents/skills/unidesk-otel/SKILL.md @@ -19,6 +19,7 @@ bun scripts/cli.ts platform-infra observability search --grep --limit ## P0 边界 +- 微服务契约版本、源码/镜像版本和 `commitId` 漂移只能记录为非阻塞 warning；不得建议或实现线上 admission、dispatch、readiness 或用户业务门禁。业务已成功时，漂移告警不能改写成功结论。 - 可见性问题优先修复；状态、耗时、失败原因、trace、命令结果或关键证据不可见时，先补 CLI/日志/状态输出。 - 离线调查中的 OTel 只能分析既有 trace 和已有业务记录；如果 trace/search/diagnose 摘要不好用、缺少业务映射或无法区分 observability gap 与业务失败，先改进 OTel CLI/analyze/instrumentation 可见性，再继续业务结论。 - OTel 查询默认低噪声摘要；完整 span/context 显式 `--full`/`--raw`。 diff --git a/AGENTS.md b/AGENTS.md index be5d44e0..4da7597e 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -49,6 +49,7 @@ ## P0: 最新要求、可见性与验证 +- P0: 微服务线上契约、版本和 `commitId` 对齐只允许非阻塞 warning，禁止阻塞用户业务；细则见 `docs/reference/devops-hygiene.md`。 - P0: 用户最新明确要求优先于旧测试、旧门禁、旧预检、旧断言和旧 guard： - 阻碍最新目标的旧入口应删除； - 不做兼容保留。 diff --git a/docs/reference/agentrun.md b/docs/reference/agentrun.md index ca23e1a5..a378bc5f 100644 --- a/docs/reference/agentrun.md +++ b/docs/reference/agentrun.md @@ -237,6 +237,10 @@ AgentRun Queue 任务如果需要调用 UniDesk 维护桥，例如 `trans` / `un ## AgentRun / HWLAB 协同职责边界 +- AgentRun 接收 HWLAB 请求时，微服务契约版本、source commit、resource commit、镜像 provenance 和部署对齐只属于诊断信息；完整规则见 + [DevOps Hygiene](devops-hygiene.md#prohibited-deployment-truth)。 +- 仅由版本或契约形态差异触发的校验必须归一化并输出非阻塞 warning，不得阻止 run、command、runner 或 session admission。 + HWLAB 接入 AgentRun 时，必须先按公共契约和运行证据判断问题归属，再进入对应仓库修改。谁拥有缺失能力、错误语义或未修复行为，就改谁；不得为了让当前联调继续推进而在另一侧迁就、伪造语义、补观测替代实现，或把缺失能力包装成已完成。 AgentRun 负责共享 Agent 执行基础设施本身，包括 run/command/runner-job 生命周期、bundle 物化、cancel、trace/result 元语、backend adapter 事件语义、runner 环境传递、CLI 结果查询和 OA 规格中已经承诺的能力。若这些能力缺失或行为错误，必须回到 UniDesk OA 规格确认需求，再在 `pikasTech/agentrun` 的源码、自测、CI/CD 和 `agentrun-v02` 运行面中补齐；HWLAB 不应在渲染层、adapter 层或 prompt 中推断、补造 AgentRun 没有发出的事实。 diff --git a/docs/reference/devops-hygiene.md b/docs/reference/devops-hygiene.md index 2662e2e7..9e0844ba 100644 --- a/docs/reference/devops-hygiene.md +++ b/docs/reference/devops-hygiene.md @@ -24,6 +24,14 @@ When declared validation dependencies are missing, install them with the reposit The following practices are not acceptable as the long-term or hidden source of a working environment: +- 微服务线上契约与版本校验必须非阻塞： + - 服务间的契约版本、源码版本、镜像版本、`commitId`、provenance 或部署对齐检查只能产生结构化 warning、OTel 事件和运维诊断； + - 这些检查不得拒绝、暂停、降级或延迟用户业务请求，也不得成为 admission、readiness、dispatch、CI/CD public gate 或 Web/CLI 可用性门禁； + - 接收方必须按当前业务语义解析请求，并对可安全归一化的旧字段、冗余字段和版本差异做兼容归一化，同时记录 warning； + - 只有业务数据本身无法解释、违反安全/权限边界或会造成不可逆损害时才允许拒绝，并返回与具体业务字段相关的 typed error； + - 禁止把版本、commit 或契约漂移包装成 `schema-invalid`、`503` 或其他用户阻塞错误； + - CI/CD、status 和 observability 可以报告版本漂移，但只能作为修复提示，不能压过真实业务成功证据。 + - Hand editing D601 runtime files, k3s manifests, ConfigMaps, Deployments or container env values and treating the live result as source of truth. - Rebuilding backend-core, frontend, k3sctl-adapter or other managed services from a dirty worktree on the master server, D601 or an operator machine. - Copying large local shell scripts, generated manifests, Docker images or application source to D601 as the main deployment mechanism. diff --git a/docs/reference/hwlab.md b/docs/reference/hwlab.md index 2656db39..544a1480 100644 --- a/docs/reference/hwlab.md +++ b/docs/reference/hwlab.md @@ -218,6 +218,12 @@ NC01 `v0.3` publicExposure 以 `config/hwlab-node-lanes.yaml` 和 PK01 Caddy/FRP ## Code Agent 模型通道 +- HWLAB 与 AgentRun 的线上契约、版本和 commit 对齐遵循 + [DevOps Hygiene](devops-hygiene.md#prohibited-deployment-truth)： + - 只允许产生非阻塞 warning 和诊断证据； + - 不得因此拒绝 Code Agent admission、dispatch 或实时事件流； + - 可安全归一化的旧请求形态必须先归一化再继续业务。 + HWLAB 的 DeepSeek/Codex 兼容性属于 HWLAB runtime 规则，长期真相在 HWLAB 仓库 `AGENTS.md` 和目标 lane 对应的 `docs/reference/`。UniDesk 指挥侧只保留监督边界：诊断这类问题时，先在选中 node/lane 的目标 Pod 或临时 passthrough Pod 内闭环证明 Codex stdio、Responses 请求、tool call/tool result 顺序、模型目录和真实 provider 返回，再考虑 GitOps/CI/CD；不要用完整 CI/CD 作为每轮协议试错工具。 DeepSeek profile 应优先使用成熟 Responses/Anthropic 协议桥接方案，例如 Moon Bridge，来保留 prompt cache、tool-result 顺序和模型目录语义。HWLAB repo-owned compatibility bridge 只能承担薄层职责，例如 Codex zstd request body 解码、非 `function` tool 过滤、`/v1/models` 或 readiness 适配；不要在 UniDesk 或 HWLAB 中手写完整 Responses-to-Chat 转换器替代成熟桥接层。Secret 值、provider token 和完整模型请求正文不得写入 UniDesk 文档、issue 或日志。 diff --git a/docs/reference/observability.md b/docs/reference/observability.md index a880193d..a109cdf6 100644 --- a/docs/reference/observability.md +++ b/docs/reference/observability.md @@ -4,6 +4,8 @@ UniDesk 的可观测性优先级高于静默成功。CLI、服务日志、Docker ## Capability Boundary +版本、commit 和微服务契约漂移只属于可观测性信号。OTel、日志、diagnose 和 status 必须把它们投影为非阻塞 warning，并继续以真实业务结果为权威；不得把漂移告警升级为业务失败、admission blocker、readiness failure 或 CI/CD gate。完整边界见 [DevOps Hygiene](devops-hygiene.md#prohibited-deployment-truth)。 + 可观测性是定位、验收和排障手段，不是功能完成标准。Trace、日志、诊断文案、fallback 标记、只读原因、降级提示和 issue 进展只能说明系统在哪里失败、为什么失败、修复后如何验证；它们不能把缺失能力包装成已完成，也不能把未修复功能包装成可接受状态。 当证据表明某条用户路径需要的能力不存在、没有真正接入、没有复用预期资源、没有返回最终业务结果，或仍停留在 mock、fixture、fallback、只读替代和提示文案时，正确动作是补齐能力或修复功能本身。允许先补最小观测来定位根因，但完成条件必须回到原始用户入口的真实行为闭环，并证明能力已经可用。