From 3b14a3e6781b7d687a9777b892dd6efb9076e36b Mon Sep 17 00:00:00 2001 From: Codex Date: Sun, 14 Jun 2026 01:31:46 +0000 Subject: [PATCH] docs: add unidesk ymalops skill --- .agents/skills/unidesk-ymalops/SKILL.md | 93 +++++++++++++++++++ .../skills/unidesk-ymalops/agents/openai.yaml | 4 + 2 files changed, 97 insertions(+) create mode 100644 .agents/skills/unidesk-ymalops/SKILL.md create mode 100644 .agents/skills/unidesk-ymalops/agents/openai.yaml diff --git a/.agents/skills/unidesk-ymalops/SKILL.md b/.agents/skills/unidesk-ymalops/SKILL.md new file mode 100644 index 00000000..30124414 --- /dev/null +++ b/.agents/skills/unidesk-ymalops/SKILL.md @@ -0,0 +1,93 @@ +--- +name: unidesk-ymalops +description: UniDesk YAML-first 运维正规化技能。用户提到 ymal-first/YAML-first 正规化、YAML ops、运维配置职责、platform-infra 配置重构、Secret sourceRef、publicExposure、target/lane/node、ops helper 抽取、删除 hardcoded defaults/特例、或 pikasTech/unidesk#339 时使用。 +--- + +# UniDesk YAML Ops + +## Scope + +本技能用于推进 UniDesk 的 `ymal-first 正规化`：把运维参数、节点/lane/service 归属、公开暴露、Secret 绑定、容量/版本/endpoint 等可调事实收敛到 YAML；代码只负责读取、校验形状、渲染计划、执行薄的 domain CLI。 + +长期跟踪 issue 是 `pikasTech/unidesk#339`。如果任务持续超过一个工作段，使用 `bun scripts/cli.ts gh issue comment create 339 --repo pikasTech/unidesk --body-stdin` 追加进度、卡点和验收证据。 + +## Required Reading + +开始前先读当前 workspace 的 `AGENTS.md`，并至少读： + +- `docs/reference/yaml-first-ops.md` +- `docs/reference/platform-infra.md`，仅当任务涉及 `platform-infra`、Sub2API、FRP/Caddy、Codex pool 或平台基础设施服务时 + +如果要修改 `docs/reference/*.md`，必须同时加载并遵循 `docs-spec`，不要凭临时经验改长期参考。 + +## Guardrails + +- 先执行 `git status --short --branch` 和 `git pull --ff-only origin master`；保留并绕开无关并行修改。 +- 源码、配置、部署类正规化默认在独立 `.worktree/` 中做；轻量 skill/docs/reference 收敛可按项目规则直接在主 worktree 做。 +- YAML 是 source of truth。不得新增隐藏代码默认值、schema 数值硬限制、合同测试或测试硬编码策略。 +- 代码校验只保证字段能被正确读取和渲染：类型、必填、枚举键名、引用存在性。版本号、namespace、endpoint、容量、冷却时间、回退窗口等数值以 YAML 为准。 +- Secret 只能通过 YAML 的 `sourceRef`/`targetKey` 声明和受控 CLI 下发；禁止从运行面 Secret、pod env、日志或数据库状态反推、解码、回填本地凭据。 +- 受控 CLI 输出只能披露对象名、key 名、sourceRef、targetKey、缺失项、fingerprint、字节数和执行摘要；不得打印 base64 payload、解码值、完整 DSN、API key 或可复制凭据。 +- 不做新的全局大 orchestrator。优先保留 domain CLI，把公共能力抽到 ops helper，domain CLI 只表达领域动作。 +- 不为了“防回归”新增合同测试、重型 preflight、历史 guard 或 feature flag。旧门禁阻碍最新 ymal-first 目标时，优先拆除。 + +## Workflow + +1. 盘点目标面：列出涉及的 YAML、CLI 入口、helper、Secret 绑定、运行面对象和现有 hardcode。 +2. 确认归属：每个事实必须有唯一 owning YAML；代码、运行面 Secret、pod env 和 docs 不能反向成为配置真相。 +3. 归一 YAML envelope：自有运维配置优先补齐 `version`、`kind`、`metadata`、`defaults`、`targets/services/lane` 等必要结构，但不要为外部工具格式强行套壳。 +4. 搬迁数值：把 namespace、serviceName、secretName、endpoint、image/tag、node/lane、probe、NO_PROXY、容量、回退窗口等可调项从代码迁到 YAML。 +5. 精简 parser：parser 只做结构和类型校验，不藏业务策略，不提供长期默认值。缺项应让 CLI 报出 YAML 路径和字段名。 +6. 抽公共 ops primitives：在增加新 service 分支前，优先复用或扩展公共 helper。 +7. 保持 domain CLI 薄：`platform-infra`、`server`、`gc`、`agentrun`、`hwlab` 等入口只组合 YAML、helper 和执行动作，不复制底层 Kubernetes/FRP/Caddy/Secret 逻辑。 +8. 验证原入口：CLI/config 改动默认只跑语法、help/命令形态、plan/dry-run 或对应 sync/validate；涉及真实运行面的收口要跑原 CLI 入口，不新增合同测试。 + +## Common Refactor Targets + +- `scripts/src/platform-infra-ops-library.ts`：应承载 namespace、Secret、resource apply、probe、public exposure 等跨服务 primitives。 +- `scripts/src/platform-infra-public-service.ts`：应成为 FRP/Caddy/public URL 渲染的共享实现，不再让每个服务复制 writer。 +- `scripts/src/pk01-caddy.ts`：PK01 Caddy/FRP 属于公共暴露能力时，应被上层 helper 调用，避免 domain CLI 直接拼配置。 +- `scripts/src/secrets.ts`：保留 sourceRef/targetKey、fingerprint、presence 语义，禁止泄露 payload。 +- `scripts/src/platform-db.ts`：host-native PostgreSQL 和 namespace-local bridge 是基础设施能力，不能让业务 service 自己硬编码 DSN 绑定。 +- `scripts/src/hwlab-node-lanes.ts` 与 `scripts/src/agentrun-lanes.ts`：lane/node 选择应来自 YAML，不应被其他 domain 复制成特例常量。 + +## Special Case Policy + +处理每个“特例”时先标注为以下三类之一，并在最终说明中列出： + +- `keep-domain-special`：真实领域差异，保留在 owning YAML 或 domain adapter 中。 +- `remove-code-default`：早期 hardcode、隐藏 fallback、重复 helper 或迁移残留，应迁到 YAML 或公共 helper。 +- `legacy-retire`：历史运行面、旧门禁、旧入口或已退役路径，应删除或只保留只读迁移说明。 + +当前倾向保留的领域特例： + +- Sub2API 的 active/standby、统一消费 key、上游账号池与 FRP 暴露关系。 +- Codex pool 的 marker-only、容量、调度候选和账号状态同步。 +- WeChat archive 依赖 D601 Windows bridge 的 host 现实。 +- PK01 host Caddy/FRP 作为公网暴露边界。 +- G14 platform PostgreSQL host-native bridge。 + +当前倾向消除的代码特例： + +- 在代码里硬编码 `G14`、`D601`、`PK01`、`platform-infra`、`sub2api`、`sub2api-secrets` 等本应来自 YAML 的默认目标。 +- `defaultTargets()`、runtime fallback、隐藏 sourceRef、隐藏 probe、隐藏 NO_PROXY 等没有 YAML 归属的默认值。 +- 重复的 `asRecord`、`stringField`、`parseEnvFile`、`fingerprintValues`、compact capture、field extraction 等 helper。 +- 各 service 自己拼 FRPC/Caddy/public URL/Secret apply 的实现。 +- 旧 contract/preflight/guard 用历史断言限制最新 YAML-first 行为。 + +## Validation + +- CLI 轻量变更：默认最多做 `bun --check`/TypeScript 语法、相关 `--help`、目标 `plan`/`validate`/`sync --dry-run` 或等价命令形态确认。 +- 配置数值变更：只验证能被目标 CLI 读取和渲染，数值本身以 YAML 为准。 +- 运行面变更：用原受控 CLI 入口验证实际对象、fingerprint、presence、health 或 public URL；不要绕到原生 `kubectl`/`curl` 作为正式控制面。 +- 不做合同测试。除非用户明确要求，不新增单元测试或测试脚本。 + +## Closeout Format + +最终回复或 issue 进展应包含： + +- owning YAML 和变更模块。 +- 保留的 `keep-domain-special` 特例。 +- 删除或迁移的 `remove-code-default` / `legacy-retire` 特例。 +- 执行过的验证命令和结果。 +- 未完成阶段、剩余风险和下一步入口。 diff --git a/.agents/skills/unidesk-ymalops/agents/openai.yaml b/.agents/skills/unidesk-ymalops/agents/openai.yaml new file mode 100644 index 00000000..5f071ea0 --- /dev/null +++ b/.agents/skills/unidesk-ymalops/agents/openai.yaml @@ -0,0 +1,4 @@ +interface: + display_name: "UniDesk YAML Ops" + short_description: "YAML-first ops normalization guide" + default_prompt: "Use $unidesk-ymalops to plan or execute a UniDesk YAML-first ops normalization change."