From 0512bdd799b92cdde56dd4397a19d8528a41ef86 Mon Sep 17 00:00:00 2001 From: pikastech Date: Mon, 20 Jul 2026 11:03:48 +0200 Subject: [PATCH] =?UTF-8?q?docs:=20=E5=9B=BA=E5=8C=96=20L1=20CLI=20?= =?UTF-8?q?=E5=8D=B3=E6=97=B6=E4=BF=AE=E5=A4=8D=E8=A7=84=E5=88=99?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- .agents/skills/unidesk-agentrun/SKILL.md | 6 ++++ .agents/skills/unidesk-devlevel/SKILL.md | 6 ++++ docs/reference/dev-environment.md | 45 ++++++++++++++++++++++-- 3 files changed, 55 insertions(+), 2 deletions(-) diff --git a/.agents/skills/unidesk-agentrun/SKILL.md b/.agents/skills/unidesk-agentrun/SKILL.md index 8f569aa6..79921a42 100644 --- a/.agents/skills/unidesk-agentrun/SKILL.md +++ b/.agents/skills/unidesk-agentrun/SKILL.md @@ -64,6 +64,12 @@ bun scripts/cli.ts agentrun native-development manager restart 或固定 HTTPS 公共入口完成内部业务回归； - Workbench smoke 必须通过产品 `--over-api` 路径提交，并只从 `hwlab.event.v1` 的 Kafka retention replay 与 live SSE 判断进展和终态； +- AgentRun L1 CLI 问题按即时修复规则处理： + - 适用于 manager、资源原语和 Workbench `--over-api` CLI； + - 问题范围包括 parser、lifecycle、窄查询、输出预算、错误码和可见性； + - 立即在当前任务内修改并做最小闭环，不等待独立授权； + - 不改用裸 REST、原生工具或临时 dump 绕过； + - 通用边界见 `docs/reference/dev-environment.md#l1-受控-cli-即时修复`。 - `runner-dispatch-*` 表示 manager 装配、观察或创建 Job 的阶段； - `runner-startup-*` 表示 Job 已创建后的 runner 启动和 backend 连接阶段； - Pod `Running` 但 runner 未 claim 时仍未进入 provider 调用，不能归因给 provider； diff --git a/.agents/skills/unidesk-devlevel/SKILL.md b/.agents/skills/unidesk-devlevel/SKILL.md index b5970cef..56f195ad 100644 --- a/.agents/skills/unidesk-devlevel/SKILL.md +++ b/.agents/skills/unidesk-devlevel/SKILL.md @@ -50,6 +50,12 @@ description: >- - 禁止用命令行覆盖、临时环境变量或隐藏 fallback 形成第二端口真相。 - 固定端口、bind/probe、首选 HTTPS origin、固定公网 HTTP 降级入口、状态目录和服务组成必须由 YAML-first 配置解析；代码和命令行不得补隐式默认值。 - L1 API、Worker、Temporal 开发依赖和 Web 的启动、停止、重启、状态、日志必须由项目 CLI 管理；`npm run`、`bun run`、`vite` 或裸脚本只允许作为 CLI 的内部实现，不是用户操作入口。 +- L1 开发、诊断或验收中发现受控 CLI 问题时，可以在当前任务内即时修改并完成最小验证： + - 问题范围包括 parser、lifecycle、transport、输出、错误码、可见性和帮助； + - 不等待独立 issue 或额外授权； + - 不把 CLI 缺陷当作只读 blocker； + - 不改用裸脚本绕过原产品入口； + - 修改范围和执行面边界以 `docs/reference/dev-environment.md#l1-受控-cli-即时修复` 为准。 - 通过项目 lifecycle 启动的 L1 服务在测试和验收后默认保持运行： - 只有用户明确要求停止或清理时才执行 stop； - 一次性 disposable smoke 可以按自身隔离合同清理，但不能替代可持续访问的 L1 服务； diff --git a/docs/reference/dev-environment.md b/docs/reference/dev-environment.md index aae08322..7e22b8ec 100644 --- a/docs/reference/dev-environment.md +++ b/docs/reference/dev-environment.md @@ -80,9 +80,50 @@ trans D601:/home/ubuntu/workspace/unidesk-dev git remote -v - 该例外使用 `CARGO_BUILD_JOBS=1`、`--jobs 1` 或 CLI 内置等价方式限制并发； - 结果必须用异步 job/status/health 证据回写 issue。 -`scripts/cli.ts`、`scripts/trans`、`scripts/tran`、`scripts/src/ssh.ts` 和相邻的 `trans`/`tran`/SSH helper 是主 server 上人工与 Codex 高频使用的控制入口；这类客户端工具链改进可以直接在 master server `/root/unidesk` 轻量修改、提交并推送到 `origin/master`。该例外只覆盖 CLI/trans/tran 客户端源码、帮助、语法/命令形态验证和对应 reference 文档，不覆盖 `src/components/provider-gateway` 行为变更、镜像构建、仓库级 check、浏览器 smoke 或其他重型验证。除非用户明确要求，CLI 改动不做单元测试、合同测试或新增测试脚本。涉及 provider-gateway 代码时仍必须遵循 provider-gateway 版本和远程升级规则。 +- 主 server 高频控制入口包括： + - `scripts/cli.ts`； + - `scripts/trans`； + - `scripts/tran`； + - `scripts/src/ssh.ts`； + - 相邻的 `trans`、`tran` 和 SSH helper。 +- 这些客户端工具链可以直接在 master server `/root/unidesk` 轻量修改、提交并推送到 `origin/master`： + - 例外范围只覆盖 CLI、`trans`、`tran` 客户端源码； + - 同时覆盖帮助、轻量语法或命令形态验证和对应 reference 文档； + - 不覆盖 `src/components/provider-gateway` 行为变更； + - 不覆盖镜像构建、仓库级 check、浏览器 smoke 或其他重型验证； + - 除非用户明确要求，CLI 改动不做单元测试、合同测试或新增测试脚本； + - 涉及 provider-gateway 代码时，继续遵循其版本和远程升级规则。 +- `trans`、`tran` 或 SSH 透传出现以下高频摩擦时，先优化 CLI 客户端： + - 文件传输、stdin、chunk 或编码； + - timeout； + - route 或 operation 解析。 +- 客户端优化应覆盖分块、校验、重试、可观测输出和帮助文档： + - 使用目标 provider、pod 或 Windows route 的最小闭环证明； + - 只有证据显示 client 侧无法规避边界时，才进入 provider-gateway 变更流程。 -当 `trans`/`tran`/SSH 透传的文件传输、stdin、chunk、编码、timeout 或 route/operation 解析出现高频摩擦时，先优化 CLI 客户端的分块、校验、重试、可观测输出和帮助文档，并用目标 provider/pod/Windows route 的最小闭环证明；只有证据显示 client 侧无法规避 provider-gateway 边界时，才进入 provider-gateway 变更流程。 +## L1 受控 CLI 即时修复 + +- 执行 L1 开发、诊断或验收时，发现项目受控 CLI 存在问题即可在当前任务内即时修改： + - 不需要把 CLI 缺陷降级为只读 blocker； + - 不需要等待独立任务、issue 或额外授权； + - 修复后继续完成原 L1 主线，不因 CLI 自身问题改用裸脚本或绕过产品入口。 +- 可即时修改的范围包括： + - YAML parser、参数校验和受控 lifecycle； + - `--over-api` transport、状态、日志和窄查询； + - 结构化输出、错误码、进度可见性和帮助文本； + - 为恢复原 L1 入口所必需的相邻轻量 helper。 +- 即时修改仍遵守原有边界： + - owning YAML 继续是运行事实唯一来源； + - 不由 CLI 缺陷推导服务端、生产、Secret、安全机制或重型构建的额外修改授权； + - 修改使用正常 Git/PR 交付路径，并保护固定 worktree 中的并行改动； + - 验证以具体文件语法、配置解析、目标命令和原 L1 入口最小闭环为准； + - 默认不新增测试，不在 Master server 运行仓库级检查或重型 smoke。 +- 以下情况属于应即时修复的 CLI 可见性问题： + - 输出缺少关键状态、失败阶段或下一步； + - 默认输出超过预算，导致无法完成判断。 + - 修复要求： + - 优先补语义化摘要、稳定 identity、分页 cursor 或 id-specific drill-down； + - 禁止长期依赖 `--raw`、临时 dump、运行面反解或裸原生工具代替受控 CLI。 ## Public Dev Frontend Port