---
name: configuring-sdlc
description: >
  sdlc-cli 全局配置（~/.sdlc/config.yaml）的自然语言前端：从对话中识别用户想配置的维度
  （workspace 根目录、产品预设 products、逻辑代码仓 repos、databases/archery/gapi.apps、飞书发布落点 feishu.folder_token），
  抽取能确定的值、对话补齐缺失项，覆盖已有值前先确认，再调用 sdlc-cli config set/get/list 写入并转述结果。
  当用户要求配置 sdlc-cli、初始化配置、添加或修改产品预设（context-repo、知识库、jira 前缀、
  关键词、产品描述）、登记代码仓地址（remote/local）或基准分支（base）、设置 workspace 根目录、
  指定飞书文档发布落点，或说
  「配置一下 checkout 产品」「把 backend 仓地址加上」「backend 默认从 develop 拉」「改一下工作区根目录」「设置 jira 前缀」
  「飞书文档推到哪个文件夹」等涉及 ~/.sdlc/config.yaml 的意图时使用。
---

# 配置 sdlc-cli（configuring-sdlc）

## 定位

本 skill 是 sdlc-cli 全局配置的**语义前端**：只负责「从自然语言识别出要配哪一项、值是什么」，
把写入动作交给 `sdlc-cli config` 命令执行（由 CLI 统一做 schema 校验、YAML 落盘）。

- **skill 做**：意图识别、语义信息抽取、与用户对话补齐缺失项、**覆盖前确认**、转述结果。
- **skill 不做**：直接读写 `~/.sdlc/config.yaml`（会绕过 schema 校验）、造默认值、删除配置项（当前不支持）。

> 配置结构、每一项的 dot-path key、值格式、缺失项问话术、常见校验错误见
> [`references/config-schema.md`](references/config-schema.md)。

---

## 主流程

### Step 1 — 识别配置维度

从用户输入判定要配置哪一个（或哪几个）维度：

| 维度 | dot-path 前缀 | 触发信号 |
|---|---|---|
| 工作区根目录 | `workspace.root` | 「工作区/workspace 根目录」「装配落到哪」「改到 ~/xxx」 |
| 产品工作区根 | `workspace.products_root` | 「产品工作区根」「products_root」「产品放到哪」「产品目录单独放」 |
| 产品预设 | `products.<产品名>.*` | 「配置 checkout 产品」「context-repo」「知识库」「jira 前缀」「产品关键词/描述」 |
| 逻辑代码仓 | `repos.<逻辑id>.*` | 「登记 backend 仓」「代码仓地址」「remote/local」「默认基准分支/base」 |
| 数据库与通道 | `databases.<key>` / `archery.*` | 「配置数据库环境」「MySQL/Redis」「Archery AK」 |
| 数据库产品归属 | `products.<产品名>.databases` | 「产品使用哪些库」「数据库列表按产品过滤」 |
| GAPI 应用 token | `gapi.apps.<应用名>.app_token` | 「给应用配 API 检索 token」 |
| 飞书发布落点 | `feishu.folder_token` | 「飞书文档推到哪个文件夹」「配一下飞书落点」「sdlc-lite 的文档放到指定目录」 |

一句话可能同时涉及多项（如「给 checkout 配 context-repo 和 jira 前缀 PROJ」）——逐项处理。

### Step 2 — 抽取值 + 对话补齐

对每一项抽取用户已明确给出的值；**不确定才问，绝不造默认值**。各维度的必填/可选字段、
取值格式、逐项问话术见 [`references/config-schema.md`](references/config-schema.md)。要点：

- [ ] **产品名 / 逻辑 id 必须由用户给定**：这是 map 的 key，不可臆造（如产品叫 checkout 还是 payment 要问清）。
- [ ] 数组类字段（`jira_prefixes` / `keywords` / 多个 `knowledge_base`）确认是「一个还是多个」，多个逐一收齐。
- [ ] `repos.<id>` 的地址：本地已存在路径记 `local`，git 地址记 `remote`（判定规则见子文件）。
- [ ] 用户指定代码仓默认基准分支时，写入 `repos.<id>.base`；用户未要求配置 base 时不主动追问。
- [ ] `repos.<id>` 的逻辑 id：默认用项目名；若与已配的 id 同名（不同 group 的同名项目），改用 `<group>/<project>` 形式，写 dot-key 时整体加引号（`'repos.sdlc/backend.remote'`）。
- [ ] 用户没提的可选字段（description、keywords 等）**不要主动追问一长串**，只配用户想配的。
- [ ] 数据库新建必须一次写完整 `databases.<key>`（type + 非空 envs），不能逐字段建立不合法的草稿。已有条目才可改子键，字段与空值规则见配置参考的「数据库与 GAPI 应用」。
- [ ] Archery 地址只读配置，无运行时默认回落。`install` / `config init` 新建配置时写入默认 base_url 与空 access_key；已有配置可用 `install` 补缺失 base_url，保留自定义地址及任何 access_key；`config init` 不覆盖已有文件。AK 缺失返回 `ARCHERY_KEY_MISSING`，AK 已有而地址缺失为配置错误（exit 1），按提示补配置后重调。
- [ ] `password` / `access_key` / `app_token` 及父级对象内的凭证输出均为 `[REDACTED]`；打码值不能用于比较原值或写回配置。转述只说明配置路径及写入结果，不回显凭证。
- [ ] `feishu.folder_token` 是**文件夹标识而非凭证**（写在飞书文件夹 URL 里，鉴权走 `lark-cli` 的 OAuth），`config get` 回真值不打码，可如实转述。用户给的是文件夹链接时，取 URL 末段的 token。**未配不是缺配**——回落个人空间根目录，用户没提落点就不要追问。

### Step 3 — 覆盖前确认（关键）

写入前，对**每一个**要写的 dot-key 先读现值：

```
sdlc-cli config get <dot-key> --json     # → {"key":..., "value": <现值 或 null>}
```

- `value` 为 `null`（未设置）→ 直接进 Step 4 写入。
- `value` 已有且**与新值不同** → 向用户展示「现值 → 新值」并请求确认：
  「`<key>` 当前是 `<现值>`，要改成 `<新值>` 吗？」用户确认才写；**用户未确认则自然停，不覆盖**。
- `value` 与新值相同 → 无需写入，告知「已是该值」。

> 为什么：`config set` 是直接覆盖，产品/仓的某个字段被无声改掉排查成本高。覆盖是用户明确要求要确认的动作。

### Step 4 — 写入

对每一项调用（始终带 `--json`）：

```
sdlc-cli config set <dot-key> <value> --json
```

- 值经 **YAML 解析**：数组传 `'[PROJ, CHK]'`、`'[git@a.git, git@b.git]'`；git 地址、`~/path` 直接裸写即可。
- 值里含 YAML 敏感前缀（`[` `{` `-` `,` 或 `: ` 冒号带空格）时，在 shell 单引号内**再套双引号**当字符串，避免被误解析。
- 产品是分组，**一次只能写一个子键**——一个产品配多个字段就多次 `config set`（每个子键各自过 Step 3）。
- 配置文件不存在时 `config set` 会自动创建，无需先 `config init`；用户明确想「初始化空配置模板」时才用 `sdlc-cli config init`。

完整 key 清单与值示例见 [`references/config-schema.md`](references/config-schema.md)。

### Step 5 — 转述并收尾

- [ ] 读返回 JSON：
  - `{"ok":true, "key":..., "value":...}` → 转述「已写入 `<key>` = `<value>`」。
  - `{"error":{"code":1, "message":"配置不合法: ..."}}` → schema 校验失败（如未知子键、类型不符、产品名拼错落到非法结构）。**如实转述 message**，据 [`references/config-schema.md`](references/config-schema.md) 的合法字段纠正后，确认再重试。
- [ ] 多项写完后，可选 `sdlc-cli config list` 展示当前完整配置，供用户核对。
- [ ] 不替用户补没确认的值，不静默吞掉校验错误。

---

## 边界（OUT）

| 不做 | 归谁 |
|---|---|
| YAML 落盘、schema 校验、点号路径解析 | `sdlc-cli config set` / `get` / `list` / `init` |
| 删除配置项 | 当前 CLI 不支持，需先明确告知用户暂不支持 |
| 用产品预设去装配工作区、跑 needs 对话环 | `assembling-workspace`（本 skill 只写配置，不触发装配） |
| 拉取 / 校验 git 地址及基准分支 | 装配时由 `ws create` 的 mirror 逻辑负责 |

---

## 参考子文件

| 子文件 | 用途 |
|---|---|
| [`references/config-schema.md`](references/config-schema.md) | 完整配置 schema、每项 dot-path key、值格式、缺失项问话术、常见校验错误 |

## 相关 skill

| 方向 | skill |
|---|---|
| 下游（配好产品/仓后装配） | `assembling-workspace`（读本 skill 写的 products / repos 预设） |
| 下游（命令怎么敲、产物怎么落位提交） | `sdlc-cli <组> -h` 与仓库 `README.md` 的命令参考表 |
| 上游（`context_repo` 指向的仓还没建，需先铺三层骨架与导航） | `initializing-context-repo` |