From cca855daa32c853f3663f1433ee0295ecba2caaa Mon Sep 17 00:00:00 2001 From: Codex Date: Thu, 25 Jun 2026 16:01:51 +0000 Subject: [PATCH] docs: specify control-plane modularization --- .../specs/PJ2026-010603-yaml-first-ops.md | 11 + ...J2026-01060307-control-plane-modularity.md | 192 ++++++++++++++++++ 2 files changed, 203 insertions(+) create mode 100644 project-management/PJ2026-01/specs/PJ2026-01060307-control-plane-modularity.md diff --git a/project-management/PJ2026-01/specs/PJ2026-010603-yaml-first-ops.md b/project-management/PJ2026-01/specs/PJ2026-010603-yaml-first-ops.md index 9679d9cf..a7174138 100644 --- a/project-management/PJ2026-01/specs/PJ2026-010603-yaml-first-ops.md +++ b/project-management/PJ2026-01/specs/PJ2026-010603-yaml-first-ops.md @@ -91,6 +91,7 @@ YAML运维负责 HWLAB/UniDesk 自有平台配置的真相源、解析、渲染 | PJ2026-01060304 | 暴露渲染 | 本规格 6.4 | publicExposure、FRP、Caddy、public URL 和 health 渲染 | 目标解析、服务入口需求 | 客户端、用户管理、Agent编排 | | PJ2026-01060305 | 执行策略 | 本规格 6.5 | AgentRun control-plane default、session policy、provider profile 和 workspace 策略配置 | Agent编排语义、lane 配置 | Agent编排、平台发布 | | PJ2026-01060306 | 公共原语 | 本规格 6.6 | 字段解析、fingerprint、摘要输出、Secret 引用和 YAML path 捕获复用 | 各平台 CLI 实现 | 全部平台运维 CLI | +| PJ2026-01060307 | 控制面模块化 | [PJ2026-01060307 控制面模块化](PJ2026-01060307-control-plane-modularity.md) | CI/CD、YAML-first 和平台运维 CLI 源码入口的职责拆分、兼容入口和模块边界 | 发布流水、源码同步、公共原语 | 全部平台运维 CLI | ## 6. 原子需求 @@ -169,3 +170,13 @@ YAML运维应沉淀公共 ops primitive，使字段解析、YAML path 捕获、f 公共 ops primitive 的职责是减少重复硬编码和输出口径漂移。领域 CLI 仍负责自身命令形态和服务语义，但不得复制一套不同的敏感输出、fingerprint、字段解析或 YAML 缺失处理规则。 受控 CLI 的默认输出必须是有界摘要、关键字段表格和下一步 drill-down 命令；`/tmp/unidesk-cli-output` dump 只能作为异常兜底，不能成为正常交互路径。完整 JSON、raw payload、完整 task/result/log、长 plan 和机器消费输出只能在显式 `--full`、`--raw`、`-o json` 或等价机器消费参数下返回，并仍须遵守 Secret 脱敏规则。 + +### 6.7 OPS-YAML-REQ-007 控制面模块化 + +| 编号 | 短名 | 主责模块 | 关联模块 | +| --- | --- | --- | --- | +| OPS-YAML-REQ-007 | 控制面模块化 | [PJ2026-01060307 控制面模块化](PJ2026-01060307-control-plane-modularity.md) | [发布流水](PJ2026-010601-controlled-release.md)、[源码同步](PJ2026-010602-source-sync.md)、[平台运维](PJ2026-0106-platform-ops.md) | + +YAML运维应约束 CI/CD、YAML-first 和平台基础设施 CLI 的源码入口，使超过 3000 行的控制面文件先按职责拆入领域子目录，再继续沉淀公共 ops primitive。 + +原 `scripts/src/*.ts` 同名入口应只保留兼容 re-export、命令路由或极薄 adapter。配置解析、manifest 渲染、远端脚本、Secret/public exposure、git-mirror、Tekton/Argo、status summary 和 bounded output 等职责应进入领域模块或共享 helper。新增平台运维逻辑不得继续追加到已超限入口文件。 diff --git a/project-management/PJ2026-01/specs/PJ2026-01060307-control-plane-modularity.md b/project-management/PJ2026-01/specs/PJ2026-01060307-control-plane-modularity.md new file mode 100644 index 00000000..fa288e91 --- /dev/null +++ b/project-management/PJ2026-01/specs/PJ2026-01060307-control-plane-modularity.md @@ -0,0 +1,192 @@ +# 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 --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//` 目录，用于承载拆分后的职责模块。 | +| 机械拆分 | 保持行为不变，把既有声明移动到职责模块并修复 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 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。纯配置、锁文件、生成产物和无法承载注释头的二进制文件可例外。