docs: 收敛 YAML 密钥引用查找路径
This commit is contained in:
Codex
@@ -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 <configRef 文件> --scope <target scope> --confirm`；领域 skill 明确声明了更具体入口时，以领域入口为准。
|
||||
- 用户进一步要求确认是否已生效、登录复测或执行下发时，才进入对应领域 skill 的受控 CLI 与运行面验证流程。
|
||||
- 详细判定与回答模板以 `docs/reference/yaml-first-ops.md#配置引用问题的最短查找路径` 为唯一权威出处。
|
||||
|
||||
## Scope
|
||||
|
||||
本技能用于推进 UniDesk 的 `ymal-first 正规化`：把运维参数、节点/lane/service 归属、公开暴露、Secret 绑定、容量/版本/endpoint 等可调事实收敛到 YAML；代码只负责读取、校验形状、渲染计划、执行薄的 domain CLI。
|
||||
|
||||
@@ -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 声明的入口为准。
|
||||
@@ -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)。
|
||||
|
||||
|
||||
@@ -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 <configRef 文件> --scope <target scope> --confirm`。
|
||||
- 标准回答必须包含：
|
||||
- owning YAML 的文件路径和对象路径；
|
||||
- `sourceRef`、可选 `sourceKey`、`targetKey`；
|
||||
- 修改动作是编辑 `sourceRef` 所指来源，而不是修改 `targetKey` 或运行面对象；
|
||||
- 修改后使用领域 skill 已声明的 `plan/status/sync/apply` 受控入口；
|
||||
- 不披露 Secret 值、完整 DSN、token 或可复制凭据。
|
||||
- 停止条件：
|
||||
- 上述字段齐全时立即回答并停止；
|
||||
- 不继续读取应用源码、数据库实现、Pod Secret、环境变量、日志或运行面；
|
||||
- 不通过字符串中 `@`、`:`、`/` 等分隔符猜测用户名或密码；
|
||||
- 只有相对 `sourceRef` 的解析基准未声明时，才定点读取领域 parser；
|
||||
- 只有用户要求验证生效或执行下发时，才进入运行面操作。
|
||||
- 回答模板：
|
||||
|
||||
```text
|
||||
owning YAML：<file>#<object.path>
|
||||
修改来源：<sourceRef>（sourceKey：<key 或“整文件”>）
|
||||
注入目标：<targetKey>
|
||||
受控入口：<domain CLI plan/status/sync/apply>
|
||||
说明：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
|
||||
|
||||
Reference in New Issue
Block a user