From c21e6df9e7802246c9f80c22ae9b900e843d4d55 Mon Sep 17 00:00:00 2001 From: Codex Date: Wed, 15 Jul 2026 11:29:02 +0200 Subject: [PATCH 1/2] =?UTF-8?q?docs:=20=E6=94=B6=E6=95=9B=20YAML=20?= =?UTF-8?q?=E5=AF=86=E9=92=A5=E5=BC=95=E7=94=A8=E6=9F=A5=E6=89=BE=E8=B7=AF?= =?UTF-8?q?=E5=BE=84?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- .agents/skills/unidesk-ymalops/SKILL.md | 24 ++++++++++ .../R3_Task_Report.md | 36 +++++++++++++++ docs/MDTODO/mdtodo-tooling-reliability.md | 2 +- docs/reference/yaml-first-ops.md | 45 +++++++++++++++++++ 4 files changed, 106 insertions(+), 1 deletion(-) create mode 100644 docs/MDTODO/details/mdtodo-tooling-reliability/R3_Task_Report.md diff --git a/.agents/skills/unidesk-ymalops/SKILL.md b/.agents/skills/unidesk-ymalops/SKILL.md index bf81a5cd..bb62cab5 100644 --- a/.agents/skills/unidesk-ymalops/SKILL.md +++ b/.agents/skills/unidesk-ymalops/SKILL.md @@ -5,6 +5,30 @@ description: UniDesk YAML-first 运维正规化技能。用户提到 ymal-first/ # UniDesk YAML Ops +## 配置引用问题快速路径 + +用户只问“YAML 引用的密钥在哪里、如何修改”或等价的配置定位问题时，固定执行以下最短路径： + +1. 读取本技能。 +2. 定位并读取该服务的 owning YAML，只查看相关 target/service 与 `sourceRef`、`sourceKey`、`targetKey`、transform、rollout/sync 字段。 +3. 直接回答： + - owning YAML 的文件和对象路径； + - `sourceRef` 指向的本地 Secret 来源； + - `sourceKey` 存在时对应来源文件内的键； + - `targetKey` 对应运行时接收键，不是用户名或 Secret 值； + - 修改来源文件后应使用的领域受控 `plan/status/sync/apply` 入口； + - 回答只披露路径、键名和入口，不读取或打印值。 +4. 信息齐全后立即停止。 + +停止条件与例外： + +- owning YAML 已给出来源、目标和受控入口所需的 selector 时，不再搜索应用源码、数据库、Pod Secret、环境变量、日志或运行面。 +- 不得根据 DSN、URL 或包含 `@` 的字符串形态猜测用户名、密码或字段边界；字段语义只由 YAML 键和对应外部格式定义。 +- `sourceRef` 为绝对路径或 `~/` 路径时按声明回答；相对路径的解析基准只有在 owning YAML 或领域 parser 未明确时才允许定点读取对应 parser，不扩大为运行面调查。 +- owning YAML 同时声明 `configRef`/`declarationId` 时，Secret 分发默认使用 `bun scripts/cli.ts secrets sync --config --scope --confirm`；领域 skill 明确声明了更具体入口时，以领域入口为准。 +- 用户进一步要求确认是否已生效、登录复测或执行下发时，才进入对应领域 skill 的受控 CLI 与运行面验证流程。 +- 详细判定与回答模板以 `docs/reference/yaml-first-ops.md#配置引用问题的最短查找路径` 为唯一权威出处。 + ## Scope 本技能用于推进 UniDesk 的 `ymal-first 正规化`：把运维参数、节点/lane/service 归属、公开暴露、Secret 绑定、容量/版本/endpoint 等可调事实收敛到 YAML；代码只负责读取、校验形状、渲染计划、执行薄的 domain CLI。 diff --git a/docs/MDTODO/details/mdtodo-tooling-reliability/R3_Task_Report.md b/docs/MDTODO/details/mdtodo-tooling-reliability/R3_Task_Report.md new file mode 100644 index 00000000..2799ca8e --- /dev/null +++ b/docs/MDTODO/details/mdtodo-tooling-reliability/R3_Task_Report.md @@ -0,0 +1,36 @@ +# R3 任务报告 + +## 目标 + +解决 UniDesk #2170，使“YAML 引用的密钥在哪里、如何修改”类问题只读取 `unidesk-ymalops` 与 owning YAML 即可回答并停止。 + +## 变更 + +- 在 `.agents/skills/unidesk-ymalops/SKILL.md` 前置配置引用快速路径、停止条件和 Secret 分发受控入口。 +- 在 `docs/reference/yaml-first-ops.md` 建立唯一详细合同，固定 `sourceRef`、`sourceKey`、`targetKey`、`configRef` 和 `transform` 的含义与回答模板。 +- 明确禁止从 `@`、`:` 等字符串形态猜测用户名或密码，也禁止为定位问题反查源码、数据库、Pod Secret、环境变量、日志或运行面。 + +## 最小 smoke + +只读取以下两个输入： + +1. `.agents/skills/unidesk-ymalops/SKILL.md` 的“配置引用问题快速路径”； +2. `config/pikaoa.yaml#releaseRuntime.targets.NC01.runtime.administrator.password`。 + +得到的脱敏答案为：owning YAML 是 `config/pikaoa.yaml`；管理员用户名由同级 `username` 声明；密码修改源由 `sourceRef` 声明；运行时接收键由 `targetKey` 声明；目标还通过 `secret.configRef`/`declarationId` 选择 Secret 分发，修改后走 `secrets sync` 受控入口。无需读取 PikaOA 源码、数据库或 Kubernetes Secret。 + +验证命令： + +```bash +git diff --check +sed -n '/配置引用问题快速路径/,/## Scope/p' .agents/skills/unidesk-ymalops/SKILL.md +sed -n '293,302p' config/pikaoa.yaml +``` + +结果：通过；输出只包含路径、用户名和键名，没有读取或打印 Secret 值。 + +## 边界与风险 + +- 本任务不修改产品源码、YAML 数值、Secret 来源内容或运行面。 +- 相对 `sourceRef` 的解析基准若未由 owning YAML 明确，仍允许定点读取领域 parser；这是唯一需要额外读取的例外。 +- 领域存在专用 Secret CLI 时，以领域 skill 声明的入口为准。 diff --git a/docs/MDTODO/mdtodo-tooling-reliability.md b/docs/MDTODO/mdtodo-tooling-reliability.md index 0c9d8a61..ec7d9502 100644 --- a/docs/MDTODO/mdtodo-tooling-reliability.md +++ b/docs/MDTODO/mdtodo-tooling-reliability.md @@ -23,7 +23,7 @@ 解决 UniDesk #1913（https://github.com/pikasTech/unidesk/issues/1913）：复用 agent_skills #7 与 PR #8 的 MDTODO 安全 stdin 实现，让主代理、Artificer resource bundle 和受控 host skill 投影默认使用安全标题输入，并有界披露 source/target freshness、warning 与精确修复入口；不得复制第二套 MDTODO 工具、增加版本门禁或覆盖宿主并行脏改，由 Artificer 在独立 worktree 和分支实现、测试并提交 PR，不自行合并，完成任务后将详细报告写入[任务报告](./details/mdtodo-tooling-reliability/R2_Task_Report.md)。 -## R3 [in_progress] +## R3 [completed] 解决 [UniDesk #2170](https://github.com/pikasTech/unidesk/issues/2170)：为 unidesk-ymalops 增加配置引用问题的 skill + owning YAML 快速收敛与停止条件，证明同类问题减少不必要工具调用，完成任务后将详细报告写入[任务报告](./details/mdtodo-tooling-reliability/R3_Task_Report.md)。 diff --git a/docs/reference/yaml-first-ops.md b/docs/reference/yaml-first-ops.md index 6b7a8da0..5c264102 100644 --- a/docs/reference/yaml-first-ops.md +++ b/docs/reference/yaml-first-ops.md @@ -1,5 +1,50 @@ # YAML-First Heterogeneous Distributed Ops +## 配置引用问题的最短查找路径 + +- 适用问题： + - YAML 引用的密钥、密码、token 或连接配置在哪里； + - 应修改哪个来源文件； + - 来源内容会写入哪个运行时键； + - 修改后应走哪个受控入口。 +- 必要输入只有两个： + - 领域 `skill`； + - 服务的 owning YAML。 +- 字段解释： + - `sourceRef` 是可修改的本地 Secret 来源或外部 Secret 引用； + - `sourceKey` 是结构化来源内被读取的键，缺省时按领域 parser 声明的整文件语义处理； + - `targetKey` 是 Secret、环境变量或渲染配置中的接收键，不代表用户名，也不包含 Secret 值； + - `transform` 描述下发前的具名转换，不能据此反向恢复原值； + - `configRef` 指向另一个 owning YAML 对象时，只沿该引用读取一次目标对象，不扫描整个仓库。 + - Secret 分发对象同时提供 `configRef`、`declarationId` 和 target scope 时，标准受控入口是 `bun scripts/cli.ts secrets sync --config --scope --confirm`。 +- 标准回答必须包含： + - owning YAML 的文件路径和对象路径； + - `sourceRef`、可选 `sourceKey`、`targetKey`； + - 修改动作是编辑 `sourceRef` 所指来源，而不是修改 `targetKey` 或运行面对象； + - 修改后使用领域 skill 已声明的 `plan/status/sync/apply` 受控入口； + - 不披露 Secret 值、完整 DSN、token 或可复制凭据。 +- 停止条件： + - 上述字段齐全时立即回答并停止； + - 不继续读取应用源码、数据库实现、Pod Secret、环境变量、日志或运行面； + - 不通过字符串中 `@`、`:`、`/` 等分隔符猜测用户名或密码； + - 只有相对 `sourceRef` 的解析基准未声明时，才定点读取领域 parser； + - 只有用户要求验证生效或执行下发时，才进入运行面操作。 +- 回答模板： + + ```text + owning YAML：# + 修改来源：（sourceKey：） + 注入目标： + 受控入口： + 说明：targetKey 不是用户名或密码；未读取或打印 Secret 值。 + ``` + +- 最小 smoke 示例只用于证明通用规则，不构成第二配置真相： + - 读取 `config/pikaoa.yaml#releaseRuntime.targets.NC01.runtime.administrator.password`； + - 可直接得到管理员用户名、密码 `sourceRef` 与 `targetKey`； + - 修改密码应编辑该 `sourceRef`，再走 PikaOA/Secret 分发的领域受控入口； + - 到此停止，无需读取 PikaOA 源码、数据库或 Kubernetes Secret。 + This document defines the UniDesk architecture for YAML-first heterogeneous distributed operations. It is the long-term reference for turning node, lane, service, Secret, exposure, database, rollout and probe decisions into declared configuration plus reusable CLI execution. Concrete values belong in YAML under `config/`; this document defines ownership and architecture only. ## Scope From 8b43e1f2fdbf1aeeac40f9797b33b4980e52b206 Mon Sep 17 00:00:00 2001 From: Codex Date: Wed, 15 Jul 2026 11:32:49 +0200 Subject: [PATCH 2/2] =?UTF-8?q?docs:=20=E7=BF=BB=E8=AF=91=20YAML-first=20?= =?UTF-8?q?=E5=8F=82=E8=80=83=E6=96=87=E6=A1=A3=E5=AF=BC=E8=AF=AD?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- docs/reference/yaml-first-ops.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/reference/yaml-first-ops.md b/docs/reference/yaml-first-ops.md index 5c264102..7fc432d9 100644 --- a/docs/reference/yaml-first-ops.md +++ b/docs/reference/yaml-first-ops.md @@ -1,4 +1,4 @@ -# YAML-First Heterogeneous Distributed Ops +# YAML-first 异构分布式运维 ## 配置引用问题的最短查找路径 @@ -45,7 +45,7 @@ - 修改密码应编辑该 `sourceRef`，再走 PikaOA/Secret 分发的领域受控入口； - 到此停止，无需读取 PikaOA 源码、数据库或 Kubernetes Secret。 -This document defines the UniDesk architecture for YAML-first heterogeneous distributed operations. It is the long-term reference for turning node, lane, service, Secret, exposure, database, rollout and probe decisions into declared configuration plus reusable CLI execution. Concrete values belong in YAML under `config/`; this document defines ownership and architecture only. +本文定义 UniDesk 的 YAML-first 异构分布式运维架构，是将节点、lane、服务、Secret、公开暴露、数据库、rollout 和探针决策收敛为声明式配置与可复用 CLI 执行的长期参考。具体数值归属于 `config/` 下的 YAML；本文只定义归属关系和架构。 ## Scope