# PJ2026-01060307 控制面模块化

## 修改历史

| 版本 | 对应 commit id | 更新日期 | 变更说明 |
| --- | --- | --- | --- |

当前正文仍在规格治理草稿中；未定稿前不新增版本号，不为单次编辑追加 `待提交` 版本。

## 正文

## PJ2026-01060307 控制面模块化需求规格

## 1. 文档控制

| 字段 | 内容 |
| --- | --- |
| 编号 | PJ2026-01060307 |
| 短名 | 控制面模块化 |
| 层级 | L3 子课题 |
| 状态 | 已生效 |
| 需求规格模板 | [ISO/IEC/IEEE 29148 需求规格模板](../../templates/iso-iec-ieee-29148-requirements-spec-template.md) |
| 上级规格 | [PJ2026-010603 YAML运维](PJ2026-010603-yaml-first-ops.md) |
| 关联规格 | [PJ2026-010601 发布流水](PJ2026-010601-controlled-release.md)、[PJ2026-010602 源码同步](PJ2026-010602-source-sync.md)、[PJ2026-010604 公开入口](PJ2026-010604-public-entry.md)、[PJ2026-010605 运维监控](PJ2026-010605-observability-monitoring.md) |
| 实现引用版本 | draft-2026-06-25-p0 |
| 规格治理索引 | [规格治理](spec-governance.md) |

本文采用 ISO/IEC/IEEE 29148 需求规格模板的项目裁剪版：正文只保留 CI/CD、YAML-first 和平台运维 CLI 控制面源码拆分的稳定目标、边界、架构、阶段和验收口径。

## 2. 目的和范围

### 2.1 目的

控制面模块化负责把 UniDesk CI/CD、YAML-first 和平台运维 CLI 中的超大 TypeScript 入口拆成可维护的领域模块，使命令路由、配置解析、manifest 渲染、远端脚本、Secret/public exposure、git-mirror、Tekton/Argo、status summary 和 bounded output 各有明确归属。

本规格的直接治理对象是超过 3000 行的控制面入口文件。第一阶段先做机械拆分和兼容入口保留，第二阶段再收紧 import/export、模块边界和共享 helper；不得在规格未落地前直接进行行为重写。

### 2.2 范围内

- `scripts/src/hwlab-g14.ts`、`scripts/src/hwlab-node-impl.ts`、`scripts/src/platform-infra-sub2api-codex.ts`、`scripts/src/agentrun.ts`、`scripts/src/platform-infra.ts`、`scripts/src/deploy.ts`、`scripts/src/artifact-registry.ts`、`scripts/src/ci.ts` 和 `scripts/src/platform-infra-observability.ts` 的职责拆分。
- 领域子目录的建立、兼容 re-export 入口、机械搬迁追溯标注和 public API 保持。
- 配置解析、manifest 渲染、远端脚本、Secret/public exposure、git-mirror、Tekton/Argo、status summary、bounded output 和低层 helper 的模块边界。
- 与 YAML-first source of truth、发布流水、源码同步、公开入口和运维监控规格的一致性。
- `bun scripts/cli.ts <domain> --help`、plan/status/validate/dry-run 等原入口 smoke 验证。

### 2.3 范围外

- GitHub CLI、Code Queue、Web/E2E、前端页面、Rust 微服务、样式文件和 trans/SSH 底座的拆分治理。
- 业务行为重写、CLI 输出契约变化、Secret 值迁移、运行面 live patch 或手工 Secret 补齐。
- 为了拆分而新增合同测试、历史 guard、feature flag 或长期兼容双路径。
- 把 YAML 职责合并成超级配置，或把运行面状态反向写成本地配置真相。

## 3. 术语表

| 术语 | 定义 |
| --- | --- |
| 薄入口 | 原 `scripts/src/*.ts` 同名文件保留的兼容层，只做 re-export、命令路由或极少量 adapter。 |
| 领域子目录 | 以控制面领域命名的 `scripts/src/<domain>/` 目录，用于承载拆分后的职责模块。 |
| 机械拆分 | 保持行为不变，把既有声明移动到职责模块并修复 import/export，不在同一阶段重写逻辑。 |
| 职责模块 | 承载一种稳定职责的实现文件，例如 options、config、manifest、remote、secrets、git-mirror、status、render、help 或 index。 |
| 公共 helper | 多个领域复用的 ops primitive，例如 bounded capture、redaction、fingerprint、Secret sourceRef、public exposure、Caddy merge 或 YAML path 解析。 |

## 4. 系统边界和接口

本规格把控制面源码模块化作为 YAML-first 运维的内部工程能力看待；它不定义业务策略数值，只定义源码职责边界和可维护性约束。

| 边界项 | 内容 |
| --- | --- |
| 外部使用者 | 平台维护者、发布操作人员、自动化任务和后续代码维护者。 |
| 外部输入 | CLI 命令、YAML 配置、node/lane/target 参数、Secret sourceRef、Git commit 和运行面状态查询请求。 |
| 受控资源 | `scripts/src` 控制面源码、领域子目录、共享 helper、兼容入口、CLI 输出摘要和原入口命令。 |
| 外部输出 | 原 CLI 命令结果、help、plan/status/validate 摘要、dry-run 计划和 redacted 错误。 |
| 用户接口 | 既有 `bun scripts/cli.ts hwlab g14 ...`、`hwlab nodes ...`、`agentrun ...`、`platform-infra ...`、`ci ...`、`deploy ...` 和 `artifact-registry ...`。 |
| 系统边界 | 本规格只要求源码职责可维护、入口兼容和 YAML-first 边界清晰；不改变运行面 desired state，不绕过受控 CLI，不以源码拆分替代业务验收。 |

## 5. 内部分工与架构

### 5.1 目标架构

```mermaid
flowchart LR
  User[CLI caller] --> Entry[thin scripts/src/*.ts entry]
  Entry --> DomainIndex[domain index/router]
  DomainIndex --> Options[options and command parsing]
  DomainIndex --> Config[domain YAML parser]
  DomainIndex --> Actions[plan apply status actions]
  Actions --> Render[manifest and summary renderers]
  Actions --> Remote[remote script builders and capture]
  Actions --> Secret[Secret/public exposure/git-mirror helpers]
  Config --> Ops[common ops primitives]
  Render --> Ops
  Remote --> Ops
  Secret --> Ops
  Ops --> Runtime[target runtime or dry-run evidence]
```

### 5.2 数据流

```mermaid
flowchart TD
  Args[explicit args or issue-selected node/lane] --> Target[target resolver]
  Yaml[owning YAML] --> Target
  Target --> Plan[redacted plan/status]
  Plan --> Action{confirm?}
  Action -- no --> Summary[bounded summary and drill-down]
  Action -- yes --> Rendered[rendered manifest/script]
  Rendered --> Controlled[UniDesk CLI or trans controlled execution]
  Controlled --> Evidence[redacted evidence and next command]
```

### 5.3 关键时序

```mermaid
sequenceDiagram
  participant Maintainer
  participant Entry as thin entry
  participant Module as domain module
  participant Helper as shared helper
  participant Runtime
  Maintainer->>Entry: bun scripts/cli.ts <domain> plan/status
  Entry->>Module: route command without hidden defaults
  Module->>Helper: parse YAML, render plan, redact secrets
  Helper-->>Module: summary, fingerprints, missing refs
  Module-->>Maintainer: bounded output and drill-down
  Maintainer->>Entry: same command --confirm when needed
  Entry->>Module: execute selected target
  Module->>Runtime: controlled CLI/trans operation
  Runtime-->>Module: status/events/log tail
  Module-->>Maintainer: redacted closeout evidence
```

## 6. 原子需求

### 6.1 OPS-MOD-REQ-001 3000 行门槛

| 编号 | 短名 | 主责模块 | 关联模块 |
| --- | --- | --- | --- |
| OPS-MOD-REQ-001 | 行数门槛 | PJ2026-01060307 控制面模块化 | [YAML运维](PJ2026-010603-yaml-first-ops.md) |

CI/CD、YAML-first 和平台运维控制面文件超过 3000 行时，必须进入职责拆分治理。原同名入口完成第一轮治理后应低于 3000 行，优先低于 800 行；新逻辑不得继续追加到已超限入口文件。

### 6.2 OPS-MOD-REQ-002 领域子目录和兼容入口

| 编号 | 短名 | 主责模块 | 关联模块 |
| --- | --- | --- | --- |
| OPS-MOD-REQ-002 | 子目录入口 | PJ2026-01060307 控制面模块化 | [源码同步](PJ2026-010602-source-sync.md) |

拆分应建立领域子目录，例如 `scripts/src/hwlab-g14/`、`scripts/src/hwlab-node/`、`scripts/src/platform-infra/`、`scripts/src/agentrun/`、`scripts/src/deploy/`、`scripts/src/artifact-registry/`、`scripts/src/ci/` 和 `scripts/src/platform-infra-observability/`。

原同名 `.ts` 文件必须保留 public API 兼容入口，继续支持既有 import 和 CLI 路由。入口层只做 re-export、命令分发或错误边界，不承载配置解析、远端脚本或大型渲染逻辑。

### 6.3 OPS-MOD-REQ-003 机械拆分优先

| 编号 | 短名 | 主责模块 | 关联模块 |
| --- | --- | --- | --- |
| OPS-MOD-REQ-003 | 机械优先 | PJ2026-01060307 控制面模块化 | [发布流水](PJ2026-010601-controlled-release.md) |

第一阶段必须优先做机械搬迁、最小 import/export 修复和原入口 smoke。每个拆出文件顶部应标注原文件和原始行段，或标注本轮从哪个原入口机械搬迁。该阶段不得同时改变 CLI 输出契约、运行面操作顺序、Secret sourceRef 规则或 YAML 解析语义。

### 6.4 OPS-MOD-REQ-004 模块边界

| 编号 | 短名 | 主责模块 | 关联模块 |
| --- | --- | --- | --- |
| OPS-MOD-REQ-004 | 模块边界 | PJ2026-01060307 控制面模块化 | [公开入口](PJ2026-010604-public-entry.md)、[运维监控](PJ2026-010605-observability-monitoring.md) |

第二阶段应把 import/export 和依赖方向收敛到稳定边界：options/config 只解析输入，manifest/render 只生成输出，remote/script builder 只封装远端执行文本，Secret/public exposure/git-mirror/Tekton/Argo/status summary 分别归属领域模块或公共 helper。

若多个领域重复实现同一机制，应优先抽到公共 helper；若差异是业务领域真实差异，应保留在领域 adapter 中并在 closeout 说明为 `keep-domain-special`。

### 6.5 OPS-MOD-REQ-005 YAML-first 与 Secret 边界

| 编号 | 短名 | 主责模块 | 关联模块 |
| --- | --- | --- | --- |
| OPS-MOD-REQ-005 | YAML边界 | PJ2026-01060307 控制面模块化 | [YAML运维](PJ2026-010603-yaml-first-ops.md)、[用户管理](PJ2026-0105-user-management.md) |

拆分后的模块不得引入新的隐藏默认值。node、lane、namespace、image、SecretRef、publicExposure、git-mirror、Tekton/Argo、endpoint、capacity、timeout 和 policy 值必须来自 owning YAML 或显式参数。

Secret 相关模块只能输出对象名、key 名、sourceRef、presence、fingerprint、字节数、缺失项和 `valuesPrinted=false`。缺 sourceRef、targetKey、providerCredential 或 tool credential 时，应暴露 YAML/AipodSpec binding 缺口，不得通过复制其他 lane Secret、手工创建 legacy Secret 或 patch runtime namespace 规避。

### 6.6 OPS-MOD-REQ-006 验证和回滚

| 编号 | 短名 | 主责模块 | 关联模块 |
| --- | --- | --- | --- |
| OPS-MOD-REQ-006 | 验证回滚 | PJ2026-01060307 控制面模块化 | [发布流水](PJ2026-010601-controlled-release.md) |

控制面模块化的默认验证是 TypeScript 语法检查、原 CLI help、目标 plan/status/validate/dry-run 和必要的只读配置引用图。涉及真实运行面 mutation 时，必须继续使用受控 CLI 入口，不以原生 `kubectl`、`argo`、`tkn`、`curl` 或临时 shell 作为正式控制面。

回滚策略是通过 Git revert 恢复模块边界，不通过复制旧文件、手工 patch 运行面或保留并行 legacy 入口实现长期双路径。若模块化后发现行为回归，应先修复 import/export 或职责边界，再决定是否回退。

## 7. 过程控制

本规格的执行 issue 为 [#903](https://github.com/pikasTech/unidesk/issues/903)。源码文件头部应标注 `SPEC: PJ2026-01060307 控制面模块化 draft-2026-06-25-p0`，并说明文件是薄入口、领域模块还是公共 helper。纯配置、锁文件、生成产物和无法承载注释头的二进制文件可例外。
