chore: remove prompt lint and contract tests
This commit is contained in:
Codex
@@ -107,9 +107,9 @@ bun scripts/cli.ts artifact-registry deploy-service --env prod --service claudeq
|
||||
|
||||
`code-queue-mgr` 是主 server Compose sidecar，不是 D601 Code Queue scheduler/runner。`artifact-registry deploy-service --env prod --service code-queue-mgr --commit <full-sha> --dry-run` 必须显示 target 仅为 `composeService=code-queue-mgr` / `containerName=code-queue-mgr-backend`，并在 `excludedTargets` 中说明不会触碰 `code-queue` scheduler、runner、任务、interrupt 或 cancel 状态。真实 prod apply 仍受 supervisor-only gate 保护；未经单服务授权不得执行非 dry-run apply。
|
||||
|
||||
`bun scripts/code-queue-cicd-dry-run-contract-test.ts` 是 Code Queue 自举边界的 focused contract：它验证 `deploy plan`、`deploy apply --dry-run` 和 `artifact-registry deploy-service --dry-run` 都只给出 DEV 计划证据，显示 `requiresSupervisorApproval` / `selfBootstrapGuard`，保持 pull-only/no-build 和 digest provenance，并证明 PROD unsupported 且不会影响生产 scheduler/runner/active tasks、interrupt 或 cancel。
|
||||
Code Queue 自举边界通过 `deploy plan`、`deploy apply --dry-run` 和 `artifact-registry deploy-service --dry-run` 验证：这些入口只给出 DEV 计划证据，显示 `requiresSupervisorApproval` / `selfBootstrapGuard`，保持 pull-only/no-build 和 digest provenance，并证明 PROD unsupported 且不会影响生产 scheduler/runner/active tasks、interrupt 或 cancel。除非用户明确要求，不为该 CLI 边界新增或运行合同测试。
|
||||
|
||||
`bun scripts/code-queue-mgr-artifact-readiness-contract-test.ts` 是 Code Queue Manager supervisor gate 的 focused source/contract 检查：它验证 prod `deploy.json` pin 到包含 stats endpoint 的 `code-queue-mgr` commit、`CI.json` 仍使用 `ci publish-user-service` 发布 `unidesk/code-queue-mgr:<commit>`、Rust runtime 暴露 `/api/tasks/stats` 且不返回 `skipped` 统计、`artifact-registry deploy-service --env prod --service code-queue-mgr --dry-run` 与 `deploy apply --env prod --service code-queue-mgr --dry-run` 都只计划 `code-queue-mgr-backend` 单个 Compose service，并保持 supervisor-only live apply、`selfBootstrapGuard` 与 scheduler/runner/tasks/interrupt/cancel excluded target 合同。
|
||||
Code Queue Manager supervisor gate 通过 dry-run 和 live health 证据验证：prod `deploy.json` 必须 pin 到包含 stats endpoint 的 `code-queue-mgr` commit，`CI.json` 仍使用 `ci publish-user-service` 发布 `unidesk/code-queue-mgr:<commit>`，Rust runtime 暴露 `/api/tasks/stats` 且不返回 `skipped` 统计，`artifact-registry deploy-service --env prod --service code-queue-mgr --dry-run` 与 `deploy apply --env prod --service code-queue-mgr --dry-run` 都只计划 `code-queue-mgr-backend` 单个 Compose service，并保持 supervisor-only live apply、`selfBootstrapGuard` 与 scheduler/runner/tasks/interrupt/cancel excluded target 边界。
|
||||
|
||||
Code Queue DEV live apply is not an automation default. The reviewed path is: publish the commit-pinned artifact, run `deploy plan --env dev --service code-queue` and `deploy apply --env dev --service code-queue --dry-run` or the equivalent artifact-registry dry-run, then have a human operator or supervisor authorize any DEV apply outside the running Code Queue task. PROD has no apply authorization point in this phase.
|
||||
|
||||
|
||||
@@ -75,9 +75,7 @@ The drift contract is:
|
||||
- Runtime topology may be mirrored in dry-run output, but deployment commands must treat it as derived target metadata and keep `noRuntimeSourceBuild=true` for reviewed artifact consumers.
|
||||
- Upstream-image services must stay `blocked` in CI source-build publishing until an upstream digest or mirror digest consumer exists.
|
||||
|
||||
Lightweight evidence for this contract is `bun scripts/issue-60-cicd-drift-contract-test.ts`. The test parses local JSON/docs only; it does not publish images, deploy services, restart containers, run Playwright or run full e2e.
|
||||
|
||||
Focused second-stage evidence is `bun scripts/issue-60-deploy-json-executor-preflight-contract-test.ts`. It runs only dry-run/contract paths, verifies the `dev/mdtodo` and `dev/decision-center` executors read image, target, port, memory and deploy metadata requirements from `deploy.json`, and simulates drift to assert field-level expected/actual error output.
|
||||
Lightweight evidence for this boundary comes from config review, `deploy plan`, `deploy apply --dry-run`, and `ci publish-user-service --dry-run` output. These checks must stay non-mutating: no image publish, service deploy, restart, Playwright or full e2e. Unless the user explicitly asks for it, do not add or run unit tests or contract tests for this CLI boundary.
|
||||
|
||||
## Artifact Catalog
|
||||
|
||||
@@ -175,22 +173,19 @@ This matrix is the single review surface for the remaining D601 service lane. It
|
||||
| `pipeline` | D601 `unidesk-direct` execution service in Docker Compose; control path is backend-core -> provider-gateway private HTTP proxy -> D601 loopback `/health` and `/api/` / `/oa/`. | `CI.json` source-build supported through `ci publish-user-service --service pipeline`; artifact is `127.0.0.1:5000/unidesk/pipeline:<commit>` from the external GitHub repo `Dockerfile`. | Reviewed D601 direct Compose artifact consumer for service `pipeline-control` / container `pipeline-v2-control`; CD is pull-only, retag, `docker compose up -d --no-build --no-deps --force-recreate pipeline-control`, then label and health verification. | Allowed after `deploy apply --env dev --service pipeline --dry-run` plus a matching registry artifact; live dev apply is permitted by policy. | Allowed after `deploy apply --env prod --service pipeline --dry-run` plus artifact/operator review; no public port or target-side build. | `/health` does not report deploy commit, so strict proof depends on image/container labels plus health. Registry health and artifact existence are required before live apply. | Add health deploy metadata and keep OA Event Flow integration checks as a focused post-apply smoke. |
|
||||
| `met-nonlinear` | D601 `unidesk-direct` GPU/business execution service in Docker Compose; control path is backend-core -> provider-gateway private HTTP proxy -> D601 loopback `/health` and `/api/`. | `CI.json` source-build supported through `ci publish-user-service --service met-nonlinear`; cataloged artifact uses `docker/unidesk/Dockerfile.ml` from `https://github.com/pikasTech/met_nonlinear`. | D601 direct Compose consumer is plan/dry-run only for service/container `met-nonlinear-ts`; dry-run exposes the no-build pull-only shape but returns `runtime-verification-blocked`. | Dry-run/read-only only. `deploy apply --env dev --service met-nonlinear --dry-run` must remain blocked until the running service image contract matches the published artifact. | Not authorized. Prod dry-run must remain `runtime-verification-blocked`; live prod apply is unsupported. | Published artifact is the ML image contract while the long-running service is `met-nonlinear-ts`, so CD cannot prove the running container image label equals the requested commit. | Split the TS server artifact from the ML image or publish a labeled artifact that exactly matches `met-nonlinear-ts`; then add live commit proof before enabling apply. |
|
||||
| `k3sctl-adapter` | UniDesk-managed D601 direct Compose control bridge, outside the native k3s fault domain; it is the control path for k3s-managed services and must not be moved into k3s. | `CI.json` source-build supported through `ci publish-user-service --service k3sctl-adapter`; artifact is `127.0.0.1:5000/unidesk/k3sctl-adapter:<commit>` from the UniDesk Dockerfile. | Artifact consumer exposes plan/dry-run only for service/container `k3sctl-adapter`; live replacement is supervisor-only because replacing the bridge can remove the repair path for k3s. | No normal dev target. DEV acceptance is read-only bridge health, service catalog/proxy checks and dry-run contract review only. | Dry-run/read-only only in this lane. Real prod replacement requires explicit supervisor confirmation, rollback proof and out-of-band recovery access. | Must remain recoverable while k3s may be broken; worker automation must not self-replace or k3s-manage the bridge. | Write a supervised bridge-upgrade runbook with rollback and out-of-band access checks; keep CLI dry-run as the standard preflight. |
|
||||
| `code-queue` | Production execution plane is D601 native k3s (`unidesk` namespace) behind `k3sctl-adapter`; dev execution plane is `unidesk-dev` scheduler/read/write/provider-egress-proxy. Main-server `code-queue-mgr` is a separate control-plane sidecar. | `CI.json` source-build supported through `ci publish-user-service --service code-queue` for dev image validation only; artifact is `127.0.0.1:5000/unidesk/code-queue:<commit>`. | Reviewed dev-only k3s artifact consumer updates only `unidesk-dev` Code Queue objects. `deploy plan --env prod --service code-queue` and `artifact-registry deploy-service --env prod --service code-queue` must stay unsupported. | Allowed only as dry-run/source/contract evidence here; a later human-approved dev live apply may consume the artifact into `unidesk-dev` outside the running Code Queue task. | Not implemented and not authorized. No production artifact deploy, manifest mutation, scheduler/runner restart, interrupt or cancel is allowed. | Production still has hostPath/source and active-run safety boundaries; self-deploy would couple the deployment actor to the target being replaced. | Keep contract tests and dev dry-run coverage; design a separate supervisor-approved production CD consumer before any prod mutation is considered. |
|
||||
| `decision-center` | D601 native k3s user service; dev runs `unidesk-dev/decision-center-dev`, prod runs `unidesk/decision-center`, both behind backend-core -> provider-gateway -> k3sctl-adapter -> Kubernetes API service proxy. | `CI.json` source-build supported through `ci publish-user-service --service decision-center`; artifact is `127.0.0.1:5000/unidesk/decision-center:<commit>` from the UniDesk Dockerfile. | Dev and prod are reviewed D601 k3s artifact consumers. Desired state, live health, and registry artifact must point at the same commit; drift where live is newer than `deploy.json` is corrected by repinning `deploy.json`, not by redeploying. | Closed for artifact CD when `deploy plan --env dev --service decision-center` is no-build and health reports matching `deploy.commit` / `deploy.requestedCommit`. Focused product gates remain record CRUD, diary lifecycle and frontend Decision Center visibility. | Closed for artifact CD when `deploy plan --env prod --service decision-center` is no-build and health reports matching `deploy.commit` / `deploy.requestedCommit`. Remaining acceptance is manual UI/product verification: health, records, diary editor, frontend page, no public business ports and live commit/artifact information. | Product completeness and manual UI acceptance can remain open, but they are not deployment drift. Registry artifact digest and health commit are the release evidence. | Keep `scripts/decision-center-desired-state-contract-test.ts` in the lightweight script gate so future desired-state edits cannot reintroduce source-build or stale-commit drift. |
|
||||
| `code-queue` | Production execution plane is D601 native k3s (`unidesk` namespace) behind `k3sctl-adapter`; dev execution plane is `unidesk-dev` scheduler/read/write/provider-egress-proxy. Main-server `code-queue-mgr` is a separate control-plane sidecar. | `CI.json` source-build supported through `ci publish-user-service --service code-queue` for dev image validation only; artifact is `127.0.0.1:5000/unidesk/code-queue:<commit>`. | Reviewed dev-only k3s artifact consumer updates only `unidesk-dev` Code Queue objects. `deploy plan --env prod --service code-queue` and `artifact-registry deploy-service --env prod --service code-queue` must stay unsupported. | Allowed only as dry-run/source evidence here; a later human-approved dev live apply may consume the artifact into `unidesk-dev` outside the running Code Queue task. | Not implemented and not authorized. No production artifact deploy, manifest mutation, scheduler/runner restart, interrupt or cancel is allowed. | Production still has hostPath/source and active-run safety boundaries; self-deploy would couple the deployment actor to the target being replaced. | Keep dev dry-run coverage; design a separate supervisor-approved production CD consumer before any prod mutation is considered. |
|
||||
| `decision-center` | D601 native k3s user service; dev runs `unidesk-dev/decision-center-dev`, prod runs `unidesk/decision-center`, both behind backend-core -> provider-gateway -> k3sctl-adapter -> Kubernetes API service proxy. | `CI.json` source-build supported through `ci publish-user-service --service decision-center`; artifact is `127.0.0.1:5000/unidesk/decision-center:<commit>` from the UniDesk Dockerfile. | Dev and prod are reviewed D601 k3s artifact consumers. Desired state, live health, and registry artifact must point at the same commit; drift where live is newer than `deploy.json` is corrected by repinning `deploy.json`, not by redeploying. | Closed for artifact CD when `deploy plan --env dev --service decision-center` is no-build and health reports matching `deploy.commit` / `deploy.requestedCommit`. Focused product gates remain record CRUD, diary lifecycle and frontend Decision Center visibility. | Closed for artifact CD when `deploy plan --env prod --service decision-center` is no-build and health reports matching `deploy.commit` / `deploy.requestedCommit`. Remaining acceptance is manual UI/product verification: health, records, diary editor, frontend page, no public business ports and live commit/artifact information. | Product completeness and manual UI acceptance can remain open, but they are not deployment drift. Registry artifact digest and health commit are the release evidence. | Keep dry-run and live health evidence sufficient so future desired-state edits cannot reintroduce source-build or stale-commit drift. |
|
||||
|
||||
Minimum evidence for this lane is:
|
||||
|
||||
| Evidence | Command |
|
||||
| --- | --- |
|
||||
| Code Queue dev/prod boundary contract | `bun scripts/code-queue-cicd-dry-run-contract-test.ts` |
|
||||
| Code Queue dev target shape | `bun scripts/cli.ts deploy plan --env dev --service code-queue` |
|
||||
| Code Queue prod unsupported shape | `bun scripts/cli.ts deploy plan --env prod --service code-queue` |
|
||||
| D601 direct Compose dry-run for `findjob` / `pipeline` | `bun scripts/cli.ts deploy apply --env dev --service <findjob|pipeline> --dry-run` |
|
||||
| MET Nonlinear blocked dry-run | `bun scripts/cli.ts deploy apply --env dev --service met-nonlinear --dry-run` |
|
||||
| k3s control bridge dry-run | `bun scripts/cli.ts deploy apply --env prod --service k3sctl-adapter --dry-run` |
|
||||
| CI producer preflight | `bun scripts/cli.ts ci publish-user-service --service <service> --commit <full-sha> --dry-run` |
|
||||
| Decision Center desired/live no-build drift guard | `bun scripts/decision-center-desired-state-contract-test.ts` |
|
||||
| Issue #60 phase-one deploy.json drift guard | `bun scripts/issue-60-cicd-drift-contract-test.ts` |
|
||||
|
||||
### Upstream Image Evidence
|
||||
|
||||
@@ -298,15 +293,7 @@ Code Queue follows the standard artifact split only up to a dev-only consumer:
|
||||
| DEV live apply | Human operator after dry-run evidence | Pull/import the existing commit image, update only `unidesk-dev` Code Queue scheduler/read/write/provider-egress-proxy objects, verify health through the Kubernetes API service proxy | Touching production `unidesk` namespace, production PostgreSQL, production scheduler/runner, running task state or Code Queue Manager prod sidecar |
|
||||
| PROD | Not implemented | Structured unsupported / dry-run evidence only | Any production Code Queue artifact deploy, manifest mutation, rollout restart, scheduler/runner rebuild, task interrupt/cancel, or self-deploy by the running Code Queue task |
|
||||
|
||||
The operator review points are fixed. DEV requires an operator to compare the CI artifact summary with `deploy plan --env dev --service code-queue` or `deploy apply --env dev --service code-queue --dry-run`, then explicitly authorize a DEV apply outside the Code Queue task. PROD has no apply authorization point in this phase; even a manual request must first land a separate reviewed Code Queue production CD design. The current runner may produce plans, preflight output, docs and contract tests only.
|
||||
|
||||
Lightweight contract evidence for this boundary is:
|
||||
|
||||
```bash
|
||||
bun scripts/code-queue-cicd-dry-run-contract-test.ts
|
||||
```
|
||||
|
||||
The test checks that dev targets only `unidesk-dev`, prod exposes no runtime deploy target, production mutation is unsupported, and dry-run output forbids Code Queue self-deploy, scheduler/runner mutation, interrupt and cancel actions.
|
||||
The operator review points are fixed. DEV requires an operator to compare the CI artifact summary with `deploy plan --env dev --service code-queue` or `deploy apply --env dev --service code-queue --dry-run`, then explicitly authorize a DEV apply outside the Code Queue task. PROD has no apply authorization point in this phase; even a manual request must first land a separate reviewed Code Queue production CD design. The current runner may produce plans, preflight output and docs only. Dry-run output must show that dev targets only `unidesk-dev`, prod exposes no runtime deploy target, production mutation is unsupported, and Code Queue self-deploy, scheduler/runner mutation, interrupt and cancel actions are forbidden.
|
||||
|
||||
## Validation Boundary
|
||||
|
||||
@@ -336,22 +323,9 @@ This matrix describes the next promotion stage after dry-run coverage is in plac
|
||||
| `k3sctl-adapter` | `master` | source-build supported | plan/dry-run only | no normal dev target; only control-bridge health and recovery evidence | prod live apply requires supervisor confirmation | bridge recovery, k3s fault-domain isolation, no worker self-replacement | `GPT-5.5` |
|
||||
| `filebrowser` / `filebrowser-d601` | `master` | upstream-image blocked | pull-only mirror target | digest resolution, mirror governance and private proxy health only | not in this phase | upstream digest/mirror worker not yet implemented | `DeepSeek` for evidence summarization, `GPT-5.5` for blocker resolution |
|
||||
|
||||
Frontend lane closure evidence is intentionally lightweight and non-mutating:
|
||||
Frontend lane closure evidence is intentionally lightweight and non-mutating: `deploy.json` dev/prod both request the same frontend commit, `CI.json` keeps the producer as `ci publish-user-service`, the D601 registry manifest digest is recorded, dev and prod health expose matching `deploy.commit` / `deploy.requestedCommit`, `ci publish-user-service --dry-run` is ready, and both CD dry-runs are artifact consumers with no source build.
|
||||
|
||||
```bash
|
||||
bun scripts/frontend-artifact-lane-contract-test.ts
|
||||
```
|
||||
|
||||
The contract fixes the current sample around one artifact lane: `deploy.json` dev/prod both request the same frontend commit, `CI.json` keeps the producer as `ci publish-user-service`, the D601 registry manifest digest is recorded, dev and prod health expose matching `deploy.commit` / `deploy.requestedCommit`, `ci publish-user-service --dry-run` is ready, and both CD dry-runs are artifact consumers with no source build.
|
||||
|
||||
User-service artifact gap reviews must report the same normalized fields for each service: `desiredCommit`, `runtimeCommit`, `artifactExists`, `devStatus`, `prodStatus`, `blockedScopes` and `recommendedAction`. The issue #9 gap contract is intentionally lightweight and non-mutating:
|
||||
|
||||
```bash
|
||||
bun scripts/issue-9-mdtodo-health-metadata-contract-test.ts
|
||||
bun scripts/issue-9-user-service-artifact-gap-contract-test.ts
|
||||
```
|
||||
|
||||
The contract pins the current `mdtodo`, `claudeqq` and `todo-note` gap surface: `deploy.json` dev/prod desired commits, `CI.json` producer metadata, structured status fields and dev/prod artifact-consumer dry-runs. `mdtodo` also has a local health metadata contract that starts the service against a temporary Markdown workspace and verifies `/health.deploy` plus `/live.deploy` before publication. These tests do not publish artifacts, apply manifests, recreate services, restart services, run full check/e2e, or probe browser UI.
|
||||
User-service artifact gap reviews must report the same normalized fields for each service: `desiredCommit`, `runtimeCommit`, `artifactExists`, `devStatus`, `prodStatus`, `blockedScopes` and `recommendedAction`. The review remains lightweight and non-mutating: `deploy.json` dev/prod desired commits, `CI.json` producer metadata, structured status fields, dev/prod artifact-consumer dry-runs, and service health metadata such as `/health.deploy` plus `/live.deploy` are the evidence. These checks do not publish artifacts, apply manifests, recreate services, restart services, run full check/e2e, or probe browser UI unless separately authorized.
|
||||
|
||||
Planned parallelism for the next wave should be three lanes:
|
||||
|
||||
|
||||
@@ -26,7 +26,7 @@ CI/CD、GitOps、rollout、artifact 发布、PR 合并后的 runtime lane 滚动
|
||||
- 每个 CLI 命名空间必须支持 `help`、`--help` 或 `-h` 并返回 JSON，不得为了打印帮助而访问 runtime 服务、拉起交互会话或执行长时任务。
|
||||
- `--main-server-ip <ip> <command>` 默认通过公网 frontend 登录态调用主 server 的同源 API 代理，不要求计算节点持有主 server SSH key；显式提供 `--main-server-key` 或 `--main-server-transport ssh` 时才使用旧 SSH 传输。远程 frontend 传输下的 `ssh <route> ...` 必须复用同一套结构化 route parser，支持 `D601`、`G14`、host workspace、`D601:win`、`D601:win/c/test`、`D601:k3s` 和 `D601:k3s:<namespace>:<workload>` 这类定位路径；它不向调用容器下发 provider token，也不要求调用容器能解析 backend-core 内网 DNS。
|
||||
- `config show` 读取并校验根目录 `config.json`，不从环境变量、默认值或隐藏文件静默补配置。
|
||||
- `check` 默认只执行轻量配置校验、Bun 版本检查和 Bun Transpiler 语法解析（覆盖 CLI 入口、主要 `scripts/` 模块和核心组件入口，不做类型推导）；关键文件存在性、`scripts/` TypeScript 类型检查、GitHub CLI live API check、`src/components/` TypeScript 类型检查、Docker Compose config、日志轮转策略扫描和 D601 recovery guardrails 默认不启用，分别通过 `--files`、`--scripts-typecheck`、`--gh-contracts`、`--components`、`--compose`、`--logs`、`--recovery-guardrails` 开启，或用 `--full` 一次性开启。`--scripts-typecheck` 只表示 scripts TypeScript 与本地脚本形态，不应触发 GitHub issue/PR live API check 这类可能受网络/API 时延影响的检查；需要验证 GitHub CLI 时显式加 `--gh-contracts`，并以该 profile 的结果判定 GitHub CLI 变更。长命令项必须在 stderr 输出 `unidesk.check.progress` JSON lines，stdout 保持最终 JSON 结果，避免 post-task 或人工运行时长时间无可见进度。`typescript:scripts` 固定通过 `bun --bun tsc -p scripts/tsconfig.json --noEmit --pretty false` 执行，默认 `--scripts-typecheck-timeout-ms 120000`，可按目标运行面显式调小或调大但 CLI 会封顶；`--check-heartbeat-ms` 控制运行中心跳间隔，默认 `15000`。所有命令项的最终 item detail 必须包含 `durationMs`、`timeoutMs`、`heartbeatMs`、`exitCode`、`signal`、`timedOut`、stdout/stderr byte count、truncation flag 和有界 tail；超时必须返回 `timedOut=true`，不得只留下被外层命令杀死的空输出。`check recovery-guardrails` 是同一诊断的低噪声直接入口，报告 malformed `/proc/mounts`、kubelet validation risk、stale CRI sandbox count、Code Queue worktree/symlink、Code Queue/MDTODO hostPath 和 `ContainerCreating` 分类；它不得重启 k3s、删除 CRI sandbox、修改 hostPath、deploy/rollout 或 prune/reset。`--rust` 只允许在 D601 CI/dev execution 中配合 `UNIDESK_D601_RUST_CHECK=1` 使用，长期规则见 `docs/reference/dev-environment.md` 和 `docs/reference/devops-hygiene.md`。
|
||||
- `check` 默认只执行轻量配置校验、Bun 版本检查和 Bun Transpiler 语法解析（覆盖 CLI 入口、主要 `scripts/` 模块和核心组件入口，不做类型推导）。除非用户明确要求，CLI 改动不运行单元测试、合同测试或新增测试脚本；默认最多做语法检查和必要的帮助/命令形态人工确认。关键文件存在性、`scripts/` TypeScript 类型检查、`src/components/` TypeScript 类型检查、Docker Compose config、日志轮转策略扫描和 D601 recovery guardrails 默认不启用，分别通过 `--files`、`--scripts-typecheck`、`--components`、`--compose`、`--logs`、`--recovery-guardrails` 开启，或用 `--full` 一次性开启。`--scripts-typecheck` 只跑 scripts TypeScript 类型检查，不触发测试脚本或 GitHub issue/PR live API check。长命令项必须在 stderr 输出 `unidesk.check.progress` JSON lines，stdout 保持最终 JSON 结果，避免 post-task 或人工运行时长时间无可见进度。`typescript:scripts` 固定通过 `bun --bun tsc -p scripts/tsconfig.json --noEmit --pretty false` 执行，默认 `--scripts-typecheck-timeout-ms 120000`，可按目标运行面显式调小或调大但 CLI 会封顶；`--check-heartbeat-ms` 控制运行中心跳间隔，默认 `15000`。所有命令项的最终 item detail 必须包含 `durationMs`、`timeoutMs`、`heartbeatMs`、`exitCode`、`signal`、`timedOut`、stdout/stderr byte count、truncation flag 和有界 tail；超时必须返回 `timedOut=true`，不得只留下被外层命令杀死的空输出。`check recovery-guardrails` 是同一诊断的低噪声直接入口，报告 malformed `/proc/mounts`、kubelet validation risk、stale CRI sandbox count、Code Queue worktree/symlink、Code Queue/MDTODO hostPath 和 `ContainerCreating` 分类；它不得重启 k3s、删除 CRI sandbox、修改 hostPath、deploy/rollout 或 prune/reset。`--rust` 只允许在 D601 CI/dev execution 中配合 `UNIDESK_D601_RUST_CHECK=1` 使用，长期规则见 `docs/reference/dev-environment.md` 和 `docs/reference/devops-hygiene.md`。
|
||||
- `server start` 创建异步 job，在后台执行 Docker 构建和启动；命令本身只负责返回 job id、日志路径和启动命令。
|
||||
- `server stop` 创建异步 job，在后台停止固定 Compose project 中的全部 UniDesk 服务。
|
||||
- `server status` 查询公开端口、受限宿主端口、内部端口、主机 swap 摘要、Compose 容器、core/frontend/dev-frontend/provider/database 健康检查和访问 URL；D601 Code Queue 使用的 PostgreSQL/OA Event Flow host mapping 必须出现在受限宿主端口而不是无条件公开入口中。低内存主 server 上 `swap.warning` 非空时，先执行 `server swap status` 或 `server swap ensure`。
|
||||
@@ -50,7 +50,7 @@ CI/CD、GitOps、rollout、artifact 发布、PR 合并后的 runtime lane 滚动
|
||||
- `dev-env validate [--manifest path] [--kubectl-dry-run]` 离线校验 D601 `unidesk-dev` namespace、dev PostgreSQL 底座和 dev workload manifest。默认检查 `src/components/microservices/k3sctl-adapter/k3s/dev/unidesk-dev-foundation.k8s.yaml`；也可显式校验 `src/components/microservices/k3sctl-adapter/k3s/dev/unidesk-dev-core.k8s.yaml` 或 `src/components/microservices/k3sctl-adapter/k3s/dev/unidesk-dev-code-queue.k8s.yaml`。所有 namespaced 对象必须只落到 `unidesk-dev`，foundation manifest 必须包含 `postgres-dev` StatefulSet/Service、dev secret/config、迁移 Job 和 DB URL guard，core manifest 必须包含 `backend-core-dev`/`frontend-dev` Deployment/Service，Code Queue dev manifest 必须包含 `code-queue-scheduler-dev`、`code-queue-read-dev`、`code-queue-write-dev`、dev provider egress proxy，以及只读挂载宿主 `/home/ubuntu/.agents/skills` 到容器 `/root/.agents/skills` 的 `skills-dir` volume。加 `--kubectl-dry-run` 时额外以 `KUBECONFIG=/etc/rancher/k3s/k3s.yaml` 执行 `kubectl apply --dry-run=client --validate=false -f <manifest>`，仍不 apply 资源；默认 `docker-desktop` kubeconfig 不得作为 D601 dry-run 目标。
|
||||
- `dev-env prewarm-images [--image image] [--provider-id D601] [--no-pull] [--proxy-url URL] [--pull-timeout-ms N] [--dry-run]` 创建异步 job，通过 UniDesk SSH 维护桥在 D601 上把开发底座依赖镜像从 Docker 缓存导入原生 k3s containerd。默认镜像是 `postgres:16-alpine` 和 `rancher/mirrored-library-busybox:1.36.1`，用于避免 `postgres-dev` 与 local-path helper pod 卡在外部 registry 拉取。该命令固定验证 `/etc/rancher/k3s/k3s.yaml` 指向的 native k3s 上下文，并输出 `dev_env_containerd_image_ready=...` 作为成功判据；它不 apply manifest、不修改生产 `unidesk` namespace。
|
||||
- `artifact-registry plan|render|status|health|install|deploy-backend-core|deploy-service` 管理 D601 host-managed CNCF Distribution registry 的声明、安装、只读检查和 pull-only artifact CD。该 registry 固定为 D601 loopback `127.0.0.1:5000`，由 systemd + Docker Compose 管理，位于 native k3s 故障域外；`deploy-service` 只拉取 CI 已发布的 commit-pinned 镜像、retag/recreate 或导入 native k3s，并做 live commit 验证，不构建 runtime source。`deploy-backend-core` 是 deprecated 兼容名，标准 backend-core prod CD 入口是 `deploy apply --env prod --service backend-core`。长期规则见 `docs/reference/artifact-registry.md`。
|
||||
- `commander contract|plan --dry-run|smoke --dry-run|approval request --dry-run|prompt-lint --kind gpt55-pr` 是 host Codex 指挥官直管微服务 skeleton 入口。当前命令返回 `phase=source-contract`、service/API/state/bridge/prompt/trace/#20/#46/ClaudeQQ 审批边界、.state/commander/ 状态模型、dev 无 daemon smoke plan、dry-run 计划和 GPT-5.5 PR prompt 边界辅助 lint，不接 live bridge、不注入 prompt、不发送 ClaudeQQ。`approval request --dry-run` 会生成 200 字以内中文纯文本 ClaudeQQ 审批草案、`notification-path-unavailable` blocker 和授权后唯一可用的 `bun scripts/cli.ts microservice proxy claudeqq /api/push/text --method POST --body-json '<payload>' --raw` 命令；不得提示使用本机 ClaudeQQ skill、powershell 或本地 server。`prompt-lint` 支持 `--prompt-file` 与 `--stdin`，输出 `ok`、`missingClauses`、`riskLevel`、`suggestedPatchSnippet` 且不回显完整 prompt；它是 commander 辅助检查，不是业务 PR 门禁；legacy `codex submit` 已冻结，新任务 payload 审查走 AgentRun `create/apply` 资源原语。`plan`、`smoke` 与 `approval request` 必须带 `--dry-run`；缺少时返回 `error=dry-run-required`。长期规则见 `docs/reference/host-codex-commander.md`。
|
||||
- `commander contract|plan --dry-run|smoke --dry-run|approval request --dry-run` 是 host Codex 指挥官直管微服务 skeleton 入口。当前命令返回 `phase=source-contract`、service/API/state/bridge/prompt/trace/#20/#46/ClaudeQQ 审批边界、.state/commander/ 状态模型、dev 无 daemon smoke plan 和 dry-run 计划，不接 live bridge、不注入 prompt、不发送 ClaudeQQ。`approval request --dry-run` 会生成 200 字以内中文纯文本 ClaudeQQ 审批草案、`notification-path-unavailable` blocker 和授权后唯一可用的 `bun scripts/cli.ts microservice proxy claudeqq /api/push/text --method POST --body-json '<payload>' --raw` 命令；不得提示使用本机 ClaudeQQ skill、powershell 或本地 server。AgentRun 新任务 payload 边界由指挥官直接审查，不再通过额外本地派单审查命令；legacy `codex submit` 已冻结，新任务走 AgentRun `create/apply` 资源原语。`plan`、`smoke` 与 `approval request` 必须带 `--dry-run`；缺少时返回 `error=dry-run-required`。长期规则见 `docs/reference/host-codex-commander.md`。
|
||||
- `hwlab g14 retirement status|plan|execute --confirm [--wait]` 是 legacy G14 DEV/PROD 的受控退役入口。`status` 只读报告 `argocd/hwlab-g14-dev`、`argocd/hwlab-g14-prod`、`hwlab-dev`、`hwlab-prod`、bounded legacy resource preview、受保护的 `hwlab-g14-v02`/`hwlab-node-v03` 和 `hwlab-v02`/`hwlab-v03`，以及 `.state/hwlab-g14/legacy-g14-retirement.json` marker。`plan` 是 dry-run，只列出 destructive targets 和 protected targets。`execute --confirm` 删除 legacy Argo Applications 与 legacy namespaces，取消本地 active `hwlab_g14_pr_monitor` job，并写 retirement marker 记录执行证据；`hwlab g14 monitor-prs --lane g14` 按退役合同固定结构化失败并指向 `retirement status` 和 runtime lane monitor `--lane v02|v03`。该入口禁止触碰 v0.2/v0.3 Application、namespace、PipelineRun、Secret、Git mirror 或 FRP desired state。
|
||||
- `hwlab g14 monitor-prs --lane v02` 是 HWLAB `v0.2` 的 PR -> CI -> CD 自动化入口。它只监控 base=`v0.2` 的 open PR：每轮先用 UniDesk `gh pr preflight` 读取 GitHub CI/checks、mergeability 和冲突状态；pending 时在 PR 下写等待评论，blocked/conflict 时写阻塞评论；ready 时直接用 UniDesk `gh pr merge` 合并，不因为其他 commit 的运行中 PipelineRun 阻塞 merge 或 CI 启动。合并后执行受控 `control-plane trigger-current --lane v02 --confirm --wait`、轮询定点 `control-plane status --lane v02 --source-commit <merge-sha>`，必要时执行 `git-mirror flush --confirm --wait`。v0.2 CD 采用 latest-only：旧 PipelineRun 不取消、不等待，但 promotion 写 `v0.2-gitops` 前必须重新确认 source head，stale commit 只能以 superseded/no-op 收口，不能回滚 runtime。不管 CD 成功、superseded、失败或超时，都在原 PR 下用 `gh pr comment create --body-stdin <<'EOF'` 追加语义化状态，正文固定包含起止时间、总耗时、冲突状态、CI/preflight conclusion、source commit、PipelineRun、targetValidation、Argo/webAssets 和 git mirror pendingFlush/githubInSync。评论去重状态写入 `.state/hwlab-g14/v02-pr-comment-signatures.json`，同一状态签名不会重复刷评论；v0.2 monitor 指针使用 `.state/hwlab-g14/latest-v02-monitor-job.json`、`latest-v02-once-job.json`、`latest-v02-dry-run-job.json` 和 `latest-v02-once-dry-run-job.json`，不会覆盖默认 G14 monitor 指针。`--lane v02 --once --dry-run` 只做单轮 preflight/merge/CD/comment plan，不写 GitHub、不触发 CD。
|
||||
- `hwlab g14 monitor-prs --lane v03` 是 HWLAB `v0.3` 的 PR -> CI -> 自动合并 -> CD 入口。它只监控 base=`v0.3` 的 open PR：每轮先通过 UniDesk `gh pr preflight` 读取 GitHub checks、mergeability 和冲突状态；pending 时只在 PR 下写等待评论；失败 check、preflight blocker 或 conflict 时在 PR 下写阻塞评论，并按标题去重创建或更新 HWLAB failure issue。ready 时通过 UniDesk `gh pr merge` 合并，随后执行 runtime lane `control-plane trigger-current --lane v03 --confirm --wait`，轮询 `control-plane status --lane v03 --source-commit <merge-sha>`，判定 PipelineRun `True`、Argo `Synced/Healthy`、`hwlab-v03` runtime workload 可见、20666/20667 public probes 通过，并在必要时执行 `git-mirror flush --lane v03 --confirm --wait`。CD 成功、失败或超时都会在原 PR 下写语义化状态评论；失败和超时同时创建或更新 failure issue，正文必须包含 PR、base/head、commit、PipelineRun、失败阶段、preflight/CD 摘要和下一步 CLI。评论去重状态写入 `.state/hwlab-g14/v03-pr-comment-signatures.json`，monitor 指针使用 `.state/hwlab-g14/latest-v03-monitor-job.json`、`latest-v03-once-job.json`、`latest-v03-dry-run-job.json` 和 `latest-v03-once-dry-run-job.json`。`--lane v03 --once --dry-run` 只做单轮 preflight/merge/CD/comment/issue plan，不写 GitHub、不触发 CD。
|
||||
@@ -74,7 +74,6 @@ CI/CD、GitOps、rollout、artifact 发布、PR 合并后的 runtime lane 滚动
|
||||
- `trans gh:/owner/repo ...` 把 GitHub issue/PR 映射成只读/受控写入的虚拟文本目录，适合日报、PR 正文和 issue 正文的小补丁维护：`trans gh:/pikasTech/HWLAB ls` 展示 `pr/` 与 `issue/`，`trans gh:/pikasTech/HWLAB/pr ls [--limit N] [--full]` 和 `trans gh:/pikasTech/HWLAB/issue ls [--limit N] [--full]` 展示条目状态、楼层数、正文长度和标题，`trans gh:/pikasTech/HWLAB/pr/507 ls` 展示单个 PR 的一楼正文文件，`trans gh:/pikasTech/HWLAB/505/1 cat|rg|patch-apply` 兼容旧式 issue/PR number route。`patch-apply` 使用 UniDesk 默认 apply-patch v2 的虚拟文件 executor，把正文一楼映射为 `body.md`，写回仍走 `bun scripts/cli.ts gh issue/pr update` 的 guard/concurrency 规则；`rm` 对正文一楼结构化拒绝，避免误删 issue/PR 正文。大正文读取必须展开 UniDesk gh dump 文件，否则 `cat/rg/patch-apply` 会误读为空，这是 `gh:` 虚拟文件接口的 P0 可见性契约。
|
||||
- `hwlab cd status|audit|preflight|apply --env dev [--dry-run]` 是旧 D601 HWLAB DEV CD 指挥侧 wrapper，仅用于显式 legacy 诊断和迁移对照。默认通过 UniDesk provider `host.ssh` 进入 D601，再调用 HWLAB repo-owned `scripts/dev-cd-apply.mjs`，不内嵌发布 kubectl 逻辑：`status` 汇总固定 CD mirror、Git clean/main/origin-main、`deploy/deploy.json`/artifact catalog/report、D601 native k3s guard 和 CD Lease lock，并用 `scripts/dev-cd-apply.mjs --status --skip-live-verify` 取得 target/promotion 摘要；`audit` 在 k3s/CD 恢复后做只读健康审计，返回有界 JSON 的 blocker 分类、D601 guard/node、SecretRef 存在性、registry 可达性、Lease phase/holder/staleness、deploy.json 与 artifact/workload image 收敛、current Deployment image/revision/rollout、16666/16667 public health commit/readiness 和 DB/runtime durability 摘要；`preflight` 进一步检查必需 SecretRef 对象/键存在性并运行 HWLAB `scripts/dev-cd-apply.mjs --dry-run --skip-live-verify` 受控事务摘要。完整远端 stdout/stderr 写入 D601 `~/.state/unidesk-hwlab-cd/<run-id>/` 和本地 `.state/hwlab-cd/<run-id>/` task dump，stdout 只返回有界摘要。默认 HWLAB CD repo 是 `/home/ubuntu/hwlab_cd`，`/home/ubuntu/hwlab` runner 历史目录不得作为发布真相。wrapper 强制 `KUBECONFIG=/etc/rancher/k3s/k3s.yaml` 并只以这个显式目标作为 gate；显式目标出现 `docker-desktop`、`desktop-control-plane` 或 `127.0.0.1:11700` 信号会结构化拒绝，audit/preflight/apply --dry-run 都必须观察到 node `d601`。真实 apply 只暴露 `scripts/dev-cd-apply.mjs --apply --confirm-dev --confirmed-non-production --write-report` 命令形状并标注 host-commander-only，本 runner 不执行 live apply、rollout、Lease mutation 或 DEV deploy apply。长期规则见 `docs/reference/hwlab.md`。
|
||||
- `gh auth status [--repo owner/name]` 探测 GitHub 操作前置条件并输出脱敏 JSON：是否存在 `gh` binary、是否存在 `GH_TOKEN`/`GITHUB_TOKEN` 或可用 `gh auth token` fallback、REST API 是否可达、目标 repo 是否可见、issue 是否可读。degraded reason 必须归类为 `missing-binary`、`missing-token`、`auth-failed`、`github-transient`、`network-proxy-failed`、`permission-denied`、`repo-not-found`、`repo-forbidden`、`issue-not-found`、`pr-not-found`、`scope-insufficient`、`validation-failed`、`invalid-response` 或 `unsupported-command`，不得打印 token；失败对象必须包含 `runnerDisposition=infra-blocked|business-failed`，runner 应优先用该字段分流。`github-transient` 表示 GitHub DNS/API 连接在收到 HTTP 状态前失败，输出应带 `retryable=true` 或等价 commander action；这不是缺 token、认证失败、权限不足或 PR 语义失败。
|
||||
- `codex prompt-lint [prompt|--prompt-file path|--prompt-stdin]` 是派发前的本地 dry-run prompt lint。它只读取 prompt 文本，返回 `dryRun=true`、`mutation=false`、`declaredClass`、`effectiveClass`、`requiredClass`、`dispatchDisposition`、缺失或矛盾项和有界 evidence，不访问 live service、不提交任务、不打印完整 prompt。分级固定为 `read-only`、`live-read`、`live-mutating`；未声明时按 `read-only` 处理。新任务走 AgentRun `create/apply` 资源原语，指挥官应把 lint 结果纳入 task manifest 或 prompt 审查。长期规则见 `docs/reference/code-queue-supervision.md` 的 DEV 测试授权分级。
|
||||
- `gh issue list [owner/repo] [--state open|closed|all] [--limit N] [--search text] [--label label[,label...]]... [--repo owner/name] [--json number,title,state,url,updatedAt,createdAt,author,labels] [--raw|--full]` 通过 GitHub REST 列出 issue，默认 `state=open`、`limit=30`，输出稳定 JSON 且不依赖系统 `gh` binary。`owner/repo` 位置参数是 `--repo owner/repo` 的兼容别名；若位置 repo 与 `--repo` 冲突，或位置参数不是 `owner/repo`，必须结构化失败，禁止静默 fallback 到默认 repo。`--limit` 是 CLI 返回上限，不等同 GitHub 单页 `per_page`：当 `--limit > 100` 或默认页中混入 PR 时，CLI 必须分页抓取 GitHub REST/Search page，过滤 PR 后再返回 issue，并在输出中披露 `pagination.fetchedPages/rawCount/hasMore`；`hasMore=true` 时只能说明当前有界扫描未穷尽，禁止把它当作“仓库没有更多 issue”。`--search` 使用 GitHub Search Issues API，并自动追加 `repo:<owner>/<name>`、`type:issue` 和 state qualifier，用于创建新 issue 前做低摩擦查重；未知 state 或未知 `--json` 字段必须结构化失败并带 `runnerDisposition=business-failed`。`--label` 是 GitHub REST `labels=label1,label2` 或 Search `label:` 服务端过滤，支持重复 `--label` 和逗号分隔；filter 不在本命令上下文中使用（如 `issue read`、`pr list`）必须结构化失败并指明 `gh issue create/list/stale-close` 才是合法作用域。GitHub issues API 可能混入 PR，CLI 会从 `.data.issues` 中过滤 pull request。`--raw|--full` 在 `gh issue list` 上是绕过 20 KiB stdout 截断的显式开关：响应结果会带 `noDump=true`，`output.ts` 据此跳过 head/tail 替换并把完整数据 inline 输出；当响应未超阈值时 `--raw|--full` 行为等价默认。
|
||||
- `gh issue lifecycle`：`--state` 只能作为 `gh issue list` / `gh issue board-row list` / `gh pr list` 的过滤参数；`gh issue update` / `gh issue edit` 只写 body/title，**不接受** `--state` 改 open/closed。把 `gh issue update <n> --state closed` 落到错命令上时，CLI 必须返回 `validation-failed` 并显式提示 `gh issue close <n>` / `gh issue reopen <n>`（PR 用 `gh pr close|reopen <n>`），并把 5 条受支持命令放进 `supportedCommands`，禁止把"无 `--state` 改 issue 状态"的命令升级为"接受 `--state`"。`gh issue close|reopen` 成功输出默认是 compact issue 摘要，不得回显完整 `issue.body`；需要正文时后续使用返回的 `readCommands` 或 `gh issue view --json body|--full|--raw`。生命周期 close/reopen 的评论推荐用 `--comment-stdin <<'EOF'` 直接写 heredoc/stdin；短单行可用 `--comment`，已有复用文件才用 `--comment-file`。需要附长篇 CLI 验收证据时，先用 `gh issue comment create <n> --body-stdin <<'EOF'` 写证据评论，再用 `gh issue close <n> --comment <短引用>` 关闭。issue 硬删除走 `close`，PR 硬删除走 `close`，两者都没有"delete"语义。
|
||||
- `gh issue comment create <number|owner/repo#number> --repo owner/name --body-stdin`、`gh issue comment update|edit <commentId> --repo owner/name --body-stdin`、`gh issue comment delete <commentId|owner/repo#number> --repo owner/name`、`gh issue close <number|owner/repo#number> --repo owner/name [--comment <text>|--comment-stdin]`、`gh issue reopen <number|owner/repo#number> --repo owner/name [--comment <text>|--comment-stdin]`、`gh issue update <number|owner/repo#number> --repo owner/name [--title ...] [--body-stdin]`、`gh issue edit <number|owner/repo#number> ...`、`gh issue board-row get|update|add|move|delete|upsert <number|owner/repo#number> --repo owner/name ...` 都接受与 `gh issue view|read`、`gh pr *` 一致的 `owner/repo#number` 位置 shorthand；shorthand 与显式 `--repo` 冲突时结构化失败并把两者都回显到错误对象里，避免静默改写目标 repo。`gh issue view|read`、`gh pr view|read|files|diff|preflight|closeout|comment create|comment update|comment edit|comment delete|close|reopen|merge|edit|update` 已长期支持该 shorthand；comment update/edit/delete 的 `--number` 表示 commentId，不是 issue/PR number。issue 写命令对齐后整个 `gh` 子命令在 shorthand 行为上保持一致，不再需要把 `pikasTech/HWLAB#621` 拆成 `621 --repo pikasTech/HWLAB`。来源：HWLAB #621 CLI 验收 `gh issue comment create pikasTech/HWLAB#621` 摩擦改进。
|
||||
|
||||
File diff suppressed because one or more lines are too long
@@ -4,7 +4,7 @@
|
||||
|
||||
P0 控制面说明：D601 生产/DEV Kubernetes 入口只允许原生 k3s；Docker Desktop Kubernetes 已停用且不得重新启用。裸 `kubectl` 仍可能命中残留 `docker-desktop` kubeconfig，不能作为 Code Queue 恢复、部署或回滚证据。详细证据和治理计划见 [pikasTech/unidesk#138](https://github.com/pikasTech/unidesk/issues/138)，2026-05-23 恢复过程见 [pikasTech/unidesk#118](https://github.com/pikasTech/unidesk/issues/118)。
|
||||
|
||||
Code Queue 后续正式生产部署必须走一条受控 CD 路径并单独审查；当前阶段只提供 dev artifact consumer 的 dry-run/source/contract readiness。`deploy apply --env dev --service code-queue --dry-run` 或 `artifact-registry deploy-service --env dev --service code-queue --dry-run` 可以计划消费 D601 registry 中的 `unidesk/code-queue:<commit>`，但输出必须显示 `selfBootstrapGuard`、`requiresSupervisorApproval`、pull-only/no-build、image tag/digest provenance，并说明只会在获授权后更新 `unidesk-dev` Code Queue execution slice。非 dry-run DEV apply 必须由 human operator/supervisor 在 Code Queue 任务之外授权；当前 Code Queue runner 不能自己上线 Code Queue。`--env prod --service code-queue` 必须明确 unsupported，不能执行生产 artifact deploy、rollout 或 manifest 变更。persistent dev apply 的完整服务范围见 `docs/reference/dev-environment.md`，Code Queue temporary smoke 仍通过 `ci run-dev-e2e`，规则见 `docs/reference/dev-ci-runner.md`。
|
||||
Code Queue 后续正式生产部署必须走一条受控 CD 路径并单独审查；当前阶段只提供 dev artifact consumer 的 dry-run/source readiness。`deploy apply --env dev --service code-queue --dry-run` 或 `artifact-registry deploy-service --env dev --service code-queue --dry-run` 可以计划消费 D601 registry 中的 `unidesk/code-queue:<commit>`，但输出必须显示 `selfBootstrapGuard`、`requiresSupervisorApproval`、pull-only/no-build、image tag/digest provenance，并说明只会在获授权后更新 `unidesk-dev` Code Queue execution slice。非 dry-run DEV apply 必须由 human operator/supervisor 在 Code Queue 任务之外授权；当前 Code Queue runner 不能自己上线 Code Queue。`--env prod --service code-queue` 必须明确 unsupported，不能执行生产 artifact deploy、rollout 或 manifest 变更。persistent dev apply 的完整服务范围见 `docs/reference/dev-environment.md`，Code Queue temporary smoke 仍通过 `ci run-dev-e2e`，规则见 `docs/reference/dev-ci-runner.md`。
|
||||
|
||||
The reproducible dry-run delivery path is:
|
||||
|
||||
@@ -13,7 +13,7 @@ The reproducible dry-run delivery path is:
|
||||
3. A human operator reviews the dry-run and, if accepted, separately authorizes DEV apply. That apply may touch only `unidesk-dev` Code Queue execution objects.
|
||||
4. PROD remains unsupported. A dry-run or plan may document the gap, but no Code Queue runner may perform prod apply, rollout restart, scheduler/runner rebuild, interrupt or cancel as part of delivering Code Queue itself.
|
||||
|
||||
This contract is checked by `bun scripts/code-queue-cicd-dry-run-contract-test.ts`. The test is intentionally lightweight and does not run full e2e, Playwright, Code Queue deployment, or task interruption flows.
|
||||
除非用户明确要求，不为该 CLI 边界新增或运行单元测试/合同测试；验证使用上述 dry-run 入口和必要的语法检查。
|
||||
|
||||
## Command
|
||||
|
||||
|
||||
@@ -14,7 +14,7 @@ The dev environment lets users experience the next UniDesk version without inter
|
||||
|
||||
## D601 UniDesk Workspace
|
||||
|
||||
`D601:UniDesk` 的固定开发 workspace 是 D601 节点上的 `/home/ubuntu/workspace/unidesk-dev`，固定使用 `master` 分支和 `origin git@github.com:pikasTech/unidesk.git`。所有需要在 D601 上改 UniDesk 代码、跑轻量合同测试、验证 `trans`/`tran`/Code Queue runner、收敛分布式敏捷实验补丁的工作，都应先进入这个目录。
|
||||
`D601:UniDesk` 的固定开发 workspace 是 D601 节点上的 `/home/ubuntu/workspace/unidesk-dev`，固定使用 `master` 分支和 `origin git@github.com:pikasTech/unidesk.git`。所有需要在 D601 上改 UniDesk 代码、做轻量语法/命令形态验证、验证 `trans`/`tran`/Code Queue runner、收敛分布式敏捷实验补丁的工作，都应先进入这个目录。
|
||||
|
||||
每次开始 D601 UniDesk 分布式开发、切换任务、恢复中断或上下文压缩后，先通过 UniDesk SSH 维护桥执行：
|
||||
|
||||
@@ -29,7 +29,7 @@ trans D601:/home/ubuntu/workspace/unidesk-dev git remote -v
|
||||
|
||||
Master server 不作为 UniDesk 重型验证机。仓库级 check、Playwright/browser smoke、镜像构建、Rust/Go 编译和 Code Queue runner 实测必须放到 D601、CI runner 或其他获批执行面；master server 只做轻量源码编辑、Git 操作、状态观察和受控调度。唯一例外是 backend-core 主 server 上线：当用户或 issue 明确要求把当前 backend-core 修复上线到主 server 时，可以用 `CARGO_BUILD_JOBS=1`、`--jobs 1` 或 CLI 内置等价限流执行 backend-core 专属编译，并必须用异步 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 或其他重型验证。涉及 provider-gateway 代码时仍必须遵循 provider-gateway 版本和远程升级规则。
|
||||
`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 版本和远程升级规则。
|
||||
|
||||
当 `trans`/`tran`/SSH 透传的文件传输、stdin、chunk、编码、timeout 或 route/operation 解析出现高频摩擦时，先优化 CLI 客户端的分块、校验、重试、可观测输出和帮助文档，并用目标 provider/pod/Windows route 的最小闭环证明；只有证据显示 client 侧无法规避 provider-gateway 边界时，才进入 provider-gateway 变更流程。
|
||||
|
||||
|
||||
@@ -90,7 +90,7 @@ bun scripts/cli.ts hwlab g14 control-plane status --lane v02 --source-commit <fu
|
||||
|
||||
Targeted status must expose `statusTarget.mode` and `targetValidation`. `targetValidation.state=passed` means the requested PipelineRun/source commit reached a succeeded PipelineRun, Argo `Synced/Healthy`, public web/API probes, flushed Git mirror, and matching runtime source commits for the services listed in that run's `planArtifacts.rolloutServices`; services listed in `planArtifacts.reusedServices` remain visible as runtime/provenance evidence but must not be forced to the target source commit. `targetValidation.state=superseded` means the requested PipelineRun succeeded but no longer owns runtime: either it was replaced by a newer succeeded `v0.2` PipelineRun, or latest-only promotion observed that `origin/v0.2` had advanced before GitOps/runtime writeback and closed the historical run as no-op. This is valid closure evidence for the requested run when the newer commit is on the same branch lineage. In both states, `commitAlignment.staleReasons` may still mention later `origin/v0.2` or CI/CD source head movement; that is parallel-head context, not a failure of the requested run. `falseGreenGuard` is a current-runtime guard and should report not-applicable/superseded for such historical targets instead of turning later runtime movement into a false failure. Default status without a target remains strict for the latest source head.
|
||||
|
||||
For HWLAB user-feedback, CLI, Cloud Web, AgentRun, device-pod, public API, or runtime workflow issues, source-level validation is not enough to close the issue. Unit tests, contract tests, `git diff --check`, targeted build checks, PR merge metadata, and source commit rollout evidence are supporting evidence only. The issue may be closed only after the affected user entry or original entry has been exercised against the target runtime. For CLI issues, that means running the relevant `hwlab-cli` or UniDesk-controlled CLI command from the G14 `v0.2` workspace or approved execution plane against the intended lane/URL/namespace and proving the observed behavior, not just proving the helper code compiles. For Cloud Web or public API issues, use the public endpoint or a bounded API/asset smoke that reaches the deployed runtime. For AgentRun or device-pod issues, capture the trace/session/thread/run/job/device evidence that proves the specific continuation or hardware workflow reached the live backend.
|
||||
For HWLAB user-feedback, CLI, Cloud Web, AgentRun, device-pod, public API, or runtime workflow issues, source-level validation is not enough to close the issue. Source checks, `git diff --check`, targeted build checks, PR merge metadata, and source commit rollout evidence are supporting evidence only. The issue may be closed only after the affected user entry or original entry has been exercised against the target runtime. For CLI issues, that means running the relevant `hwlab-cli` or UniDesk-controlled CLI command from the G14 `v0.2` workspace or approved execution plane against the intended lane/URL/namespace and proving the observed behavior, not just proving the helper code compiles. For Cloud Web or public API issues, use the public endpoint or a bounded API/asset smoke that reaches the deployed runtime. For AgentRun or device-pod issues, capture the trace/session/thread/run/job/device evidence that proves the specific continuation or hardware workflow reached the live backend.
|
||||
|
||||
For Cloud Web Workbench and Code Agent issues, the closeout validation must use the same dispatch entry as the browser flow, or a CLI command that calls that same Cloud Web/Cloud API dispatcher path. A hand-written `dispatchHwlabAgentRun()` canary, direct AgentRun manager command, or runner job created outside the Web dispatcher is only infrastructure evidence; it cannot prove that the browser path requested the current AgentRun runtime assembly, tool credentials, transient env, conversation/session/thread binding, or runtime lane. The current HWLAB v0.2 resource assembly contract is `ResourceBundleRef.kind="gitbundle"` with `bundles[]` materializing repo `tools/` and `skills/`; the authority for those fields is HWLAB's `docs/reference/agentrun-code-agent-dispatch.md` and AgentRun's `docs/reference/spec-v01-runtime-assembly.md`. If no CLI can exercise the Web-equivalent path, improve the CLI first and keep the issue open until the Web-equivalent CLI or browser trace proves the deployed behavior.
|
||||
|
||||
@@ -160,12 +160,12 @@ Cloud Web layout, status-panel, collapsed-control, and modal issues on `v0.2` ne
|
||||
|
||||
Use these surfaces together:
|
||||
|
||||
- `trans G14:/root/hwlab-v02/.worktree/<task>/web/hwlab-cloud-web script -- 'bun run check'` for static unit/contract/layout checks and dist freshness.
|
||||
- `trans G14:/root/hwlab-v02/.worktree/<task>/web/hwlab-cloud-web script -- 'bun run check'` for approved static source/layout checks and dist freshness.
|
||||
- `bun scripts/cli.ts hwlab g14 control-plane status --lane v02` for runtime, Argo, public endpoint, and GitOps alignment. If `origin/v0.2` moved through a parallel PR, use `--pipeline-run` or `--source-commit` and treat same-branch supersession as context rather than failure.
|
||||
- Public API probes for both `/health/live` and `/v1/live-builds`. `/health/live` proves live service health/revision, but Cloud Web build time, image tag/digest, source metadata, and actual runtime commit/revision should be read from `/v1/live-builds`.
|
||||
- A bounded browser/DOM probe against `http://74.48.78.17:19666/` that asserts the deployed page state relevant to the issue.
|
||||
|
||||
Cloud Web frontend regressions still use the two-layer validation rule. Deterministic client behavior, such as scroll-follow state machines, Markdown/HTML escaping, shared renderer output, persisted view mapping and DOM class/attribute decisions, should be reproduced first in source-level unit or contract tests; those tests may mock DOM nodes, API responses or renderer input because they are the fast regression guard. The deployed browser or Web-equivalent CLI layer must not mock the user entry, and should prove only the live integration that unit tests cannot prove: the public bundle is deployed, the real page dispatch path creates the expected DOM state, and the user-visible control behaves on the target lane. Do not move every frontend bug into CLI/browser smoke just because it is user-facing.
|
||||
Cloud Web frontend regressions still use the two-layer validation rule when approved by the task: deterministic source-level checks can cover scroll-follow state machines, Markdown/HTML escaping, shared renderer output, persisted view mapping and DOM class/attribute decisions; the deployed browser or Web-equivalent CLI layer must not mock the user entry, and should prove only the live integration that source-level checks cannot prove: the public bundle is deployed, the real page dispatch path creates the expected DOM state, and the user-visible control behaves on the target lane. Do not move every frontend bug into CLI/browser smoke just because it is user-facing.
|
||||
|
||||
Cloud Web message Markdown must go through a single shared React renderer component. Do not maintain a hand-written Markdown parser or a `dangerouslySetInnerHTML` message path for normal chat/workbench messages. The shared renderer's fast tests should cover at least GFM table rendering, inline/fenced code, emphasis/strong text and raw HTML escaping. Browser closeout should assert rendered DOM shape, such as `table`/`code`/`strong` counts and absence of injected `script` nodes or executed script flags, instead of comparing the full rendered HTML string.
|
||||
|
||||
|
||||
@@ -27,14 +27,11 @@ bun scripts/cli.ts commander contract
|
||||
bun scripts/cli.ts commander plan --dry-run [--session-id primary]
|
||||
bun scripts/cli.ts commander smoke --dry-run [--session-id primary]
|
||||
bun scripts/cli.ts commander approval request --action <action> --dry-run [--reason text] [--task-id id]
|
||||
bun scripts/cli.ts commander prompt-lint --kind gpt55-pr (--prompt-file <file>|--stdin)
|
||||
```
|
||||
|
||||
`plan`、`smoke` 与 `approval request` 必须显式使用 `--dry-run`，缺失时返回 `error=dry-run-required`。
|
||||
|
||||
`commander prompt-lint --kind gpt55-pr` 是指挥官派 GPT-5.5 PR/收口类任务前的本地辅助检查。它只读取 `--prompt-file` 或 `--stdin`，返回结构化 JSON 字段 `ok`、`missingClauses`、`riskLevel`、`suggestedPatchSnippet`、`promptShape.textEchoed=false` 和 `policy.advisoryOnly=true`；不会提交 Code Queue task、不会修改 scheduler、不会访问 live service，也不会回显完整 prompt。即使 lint 发现缺失条款，CLI envelope 仍保持成功退出，调用方应把 `data.ok=false` 当作派单前修补建议，而不是业务 PR 门禁或 `codex submit` admission 规则。
|
||||
|
||||
`gpt55-pr` 当前检查的硬边界包括：普通 PR 创建/更新、自合并/关闭、rebase/update/冲突处理授权；repo-owned CI/CD、build/publish artifact、DEV image/artifact tag/digest/report 授权；DEV deploy apply、rollout 和 live health verification 默认由 host commander 统一执行；未显式包含 `ROLLOUT_OK` 时 runner 不得竞争 DEV CD lock、deploy apply、rollout 或 live verification；禁止 PROD mutation、密钥读取/打印、数据库手工写入和破坏性回滚。缺失时 `suggestedPatchSnippet` 只给可追加的边界片段，不包含原 prompt。
|
||||
GPT-5.5 PR/收口类任务的边界由指挥官在 AgentRun 派单前直接审查，prompt 必须写清 PR 创建/更新、自合并/关闭、rebase/update/冲突处理、repo-owned CI/CD、artifact build/publish、DEV rollout、PROD/secret/DB/破坏性回滚禁止范围和 closeout 字段。
|
||||
|
||||
## Operator-Run Stdio Loop
|
||||
|
||||
@@ -86,14 +83,12 @@ host commander 不直接编辑 HWLAB 业务代码，不以本地热修绕过 HWL
|
||||
- approval draft preview：只运行 `commander approval request --dry-run` 或 `buildCommanderApprovalDraft`，确认 `requiresExplicitUserApproval=true`、`claudeqq.mutation=false`、`sendImplemented=false`、`dryRunNoClaudeQqSend=true`、`notificationDraft.message` 为 200 字以内中文纯文本、`notificationPath.error=notification-path-unavailable`，并返回 backend-core `microservice proxy claudeqq /api/push/text` 命令；禁止 POST ClaudeQQ。
|
||||
- SSH bridge boundary：只检查 `commander plan --dry-run` 中 `bridge.mutation=false`、`startPlan.enabled=false` 和 `safetyBoundary.phaseOneMutationAllowed=false`；禁止打开 SSH、PTY 或 stdio bridge。
|
||||
|
||||
历史命名的 dry-run 脚本是：
|
||||
默认 dry-run 验证入口是：
|
||||
|
||||
```bash
|
||||
bun scripts/host-codex-commander-no-daemon-smoke-contract-test.ts
|
||||
bun scripts/cli.ts commander smoke --dry-run
|
||||
```
|
||||
|
||||
该脚本保留历史 `contract-test` 文件名，但只执行 CLI dry-run 和短命 source-level handler/helper，不启动长期进程，也不代表新增合同测试政策。
|
||||
|
||||
## HTTP
|
||||
|
||||
| Method | Path | 说明 |
|
||||
|
||||
@@ -95,4 +95,4 @@ Pipeline 的最终控制模型必须是 100% OA 事件流驱动。开发过程
|
||||
- 完成态还必须删除文件传输残留：`PIPELINE_MONITOR_APPEND_FILE`、`PIPELINE_MONITOR_STOP_FILE`、`PIPELINE_MONITOR_CONTROL_DIR`、`PIPELINE_NODE_PROMPT_APPEND_FILE`、`control-events.jsonl`、`runControlEventFile`、`appendJsonLine`、`readJsonLineRecords`、`readPromptAppendFile`、`parseCommandFile`、`parseMonitorCommandFile`、`readMonitorCommands`、`fallbackMonitorInterventions`、`syntheticMonitorStopPrompt` 以及 monitor 的 `/pipeline-state` 挂载都不得出现在运行代码中。
|
||||
- E2E 必须覆盖有审核与无审核两条链路：无审核时由 OA 从 `node-finished` 推进下游；有审核时由 monitor 经 OA 控制事件推进下游；事件都必须带 `pipeline:{pipelineId}` 与 `epoch:{runId}` tag。
|
||||
- Pipeline 甘特图 E2E 必须证明没有重复审核点、长任务观察有连线且无来源伪点、running node 有实时条、OpenCode step 空闲区间留白、控制箭头来自 OA 控制事件。
|
||||
- 代码检查应加入防回归搜索或等价单元测试，防止重新引入 `legacy audit policy flag` 权威字段、旧 audit-request 事件、`legacy batch completion gate` 推进逻辑或非 OA 控制写路径。
|
||||
- 代码检查应优先使用防回归搜索或原入口验证，防止重新引入 `legacy audit policy flag` 权威字段、旧 audit-request 事件、`legacy batch completion gate` 推进逻辑或非 OA 控制写路径；除非用户明确要求，不新增测试脚本。
|
||||
|
||||
@@ -69,7 +69,7 @@
|
||||
|
||||
**遇到 CLI 报错或"看起来锁了"的现象，不要凭错误文案下结论；按"读源码 + 容器内实测 + git history + 复盘 issue"四步调查。** 第一步读 microservice 源码（UniDesk 主仓 vendoring 的镜像源或外部仓的 `server.ts` / `microservice_proxy.rs`），定位注册路由表、mode 标志位、错误文案生成点；第二步在容器内直接实测（`docker exec ... node ...` 或 `wget http://service:port/...`），拿到真实 200 / 4xx 响应，验证假设；第三步查 git history 看是谁、什么时候、为什么加的；第四步把"原诊断 + 真因 + 实测证据 + 修复点"蒸馏到 `docs/reference/` 并开/更新对应 issue（参考 [pikasTech/unidesk#188](https://github.com/pikasTech/unidesk/issues/188) 复盘结构）。特别警惕"错误文案暗示的因果"——例如 `404 {"error":"X is running in backend-only mode"}` 不代表 mode 锁了写，只代表请求路径没匹配上 catch-all；模式措辞误导是常见陷阱。
|
||||
|
||||
**CLI 改进用直接交互调用验证，不写测试脚本**（[cli-friction-no-over-testing](file:///home/ubuntu/.claude/projects/-home-ubuntu-unidesk/memory/cli-friction-no-over-testing.md) 原则）。一次性的根 CLI 调用范式、参数形态、shell escape 规避和端点可用性，直接 `bun scripts/cli.ts ...` 跑一次看 200 / body 就够了；远端透传范式直接 `trans <route> ...` 验证。不要为一次性改进堆 `bun:test` / `mocha` / `jest` 的 contract test。contract test 只在结构性边界（如 action type 全清单、权限边界、长期回归）需要时才写。`docs/reference/cli.md` 已固化的 CLI 范式都经过 2026-06-01 交互验证（actions 端点 addTodo / toggleTodoCompleted / deleteTodo 全部 200 OK），见 cli.md 的 Todo Note 写操作段。
|
||||
**CLI 改进用直接交互调用验证，不写测试脚本**（[cli-friction-no-over-testing](file:///home/ubuntu/.claude/projects/-home-ubuntu-unidesk/memory/cli-friction-no-over-testing.md) 原则）。一次性的根 CLI 调用范式、参数形态、shell escape 规避和端点可用性，直接 `bun scripts/cli.ts ...` 跑一次看 200 / body 就够了；远端透传范式直接 `trans <route> ...` 验证。除非用户明确要求，不为 CLI 改动新增或运行 `bun:test` / `mocha` / `jest` / contract test；默认最多做语法检查和必要命令形态确认。`docs/reference/cli.md` 已固化的 CLI 范式都经过 2026-06-01 交互验证（actions 端点 addTodo / toggleTodoCompleted / deleteTodo 全部 200 OK），见 cli.md 的 Todo Note 写操作段。
|
||||
|
||||
**秘书的本份是维护 Todo Note；Decision Center diary 是用户自己的工作日志，秘书只读不写。** 收到用户口述的进展（完成/未完成/卡点/决策/排程登记），秘书维护 Todo Note（标 completed / 新增子 todo / 拆分 / 改 reminder），不写到 diary。Decision Center diary 是用户承载自己反思和工作日志的私域，秘书写进去等于抢用户的笔、污染第一人称叙述。例外只有读：秘书可以调用 `diary show` / `diary list` / `diary months` 对齐上下文，**不调用 `diary upsert` / `diary edit` / `diary import` / `diary today`**。当 Todo Note 写路径被外部阻塞（如 issue #188 的 backend-only mode）时，秘书必须先把修复升级到日程或明确告诉用户「无法维护 Todo Note,你的进展请你自己在 Todo Note 里勾完成」，不能绕道用 diary 替代。
|
||||
|
||||
|
||||
@@ -68,7 +68,7 @@ Frontend is the canonical user-service UI sample. It is not released by target-s
|
||||
|
||||
- The minimal standard artifact command is `bun scripts/cli.ts ci publish-user-service --service frontend --commit <full-sha> --wait-ms 1200000`.
|
||||
- The expected artifact is `127.0.0.1:5000/unidesk/frontend:<commit>` plus its registry digest from the CI output.
|
||||
- The lightweight closure contract is `bun scripts/frontend-artifact-lane-contract-test.ts`. It checks `deploy.json` dev/prod desired commits, the `CI.json` producer entry, the observed registry digest, dev/prod `/health.deploy.commit` and `deploy.requestedCommit`, producer dry-run readiness, and dev/prod CD dry-run no-build targets.
|
||||
- Lightweight closure evidence checks `deploy.json` dev/prod desired commits, the `CI.json` producer entry, the observed registry digest, dev/prod `/health.deploy.commit` and `deploy.requestedCommit`, producer dry-run readiness, and dev/prod CD dry-run no-build targets.
|
||||
- Dev CD consumes the same artifact with `bun scripts/cli.ts deploy apply --env dev --service frontend`; it imports the image into D601 native k3s, rolls out `frontend-dev`, syncs auth/session metadata from main-server config, and verifies `/health.deploy.commit`.
|
||||
- Production CD consumes the same artifact with `bun scripts/cli.ts deploy apply --env prod --service frontend`; it recreates only the master-server Compose `frontend` service with `--no-build --no-deps --force-recreate` and verifies image labels plus `/health.deploy.commit`.
|
||||
- `server rebuild frontend` remains a maintenance/local rebuild path only. It is not the standard versioned release truth for frontend.
|
||||
@@ -164,7 +164,7 @@ MDTODO is a k3s-managed user-service artifact consumer.
|
||||
|
||||
- The minimal standard artifact command is `bun scripts/cli.ts ci publish-user-service --service mdtodo --commit <full-sha> --wait-ms 1200000`.
|
||||
- The expected artifact is `127.0.0.1:5000/unidesk/mdtodo:<commit>` plus its registry digest from the CI output.
|
||||
- The selected commit must include the `UNIDESK_DEPLOY_*` health metadata contract; `bun scripts/issue-9-mdtodo-health-metadata-contract-test.ts` is the focused local guard for `/health.deploy` and `/live.deploy`.
|
||||
- The selected commit must include the `UNIDESK_DEPLOY_*` health metadata surface; `/health.deploy` and `/live.deploy` are verified through service health or dry-run/live entry evidence, not through default contract tests.
|
||||
- Dev CD must run before prod CD and lands in `unidesk-dev/mdtodo-dev`; production CD lands in `unidesk/mdtodo`.
|
||||
- Both paths must verify Deployment metadata and `/health` or `/live` deploy commit through the Kubernetes API service proxy.
|
||||
- No MDTODO release may add NodePort, hostPort, public business ports or provider-gateway direct business backends.
|
||||
|
||||
Reference in New Issue
Block a user