refactor(psutils): 抽取配置对象读取助手

Author: mudssky

.trellis/spec/psutils/package/shared-config-resolver.md

@@ -23,6 +23,7 @@
   - `Read-ConfigMarkdownFrontMatter -Path <string>`
 - Conversion helpers:
   - `ConvertTo-ConfigHashtable -InputObject <object>`
+  - `Get-ConfigValue -Values <hashtable> -Name <string> [-DefaultValue <object>]`
   - `ConvertTo-ConfigKeyName -Name <string>`
   - `ConvertFrom-ConfigCliParameters -Parameters <hashtable> [-ExcludeKeys <string[]>]`
 - Scoped env:
@@ -37,6 +38,7 @@
 - `Resolve-DefaultEnvFiles -PrimaryBasePath <dir> -FallbackBasePath <dir>` only falls back when the primary directory has no default env file at all.
 - `CliParameters` converts explicit PowerShell parameters to snake_case keys and skips `$null`、empty strings and `ExcludeKeys`.
 - `MarkdownFrontMatter` returns parsed metadata plus `__content` for the Markdown body.
+- `Get-ConfigValue` performs shallow case-insensitive lookup only; it must not expand paths, environment variables, nested paths, or normalize key names.
 - Missing file sources return an empty table by default; `-ErrorOnMissing` changes that to `配置文件不存在: <path>`.
 - `Invoke-WithScopedEnvironment` must restore overwritten variables and remove newly created variables even when the script block throws.
 - `psutils/modules/config.psm1` must export public resolver functions and must not contain a second implementation of the parser.

.trellis/tasks/05-20-05-20-skills-config-helper-extraction/check.jsonl

@@ -0,0 +1 @@
+{"_example": "Fill with {\"file\": \"<path>\", \"reason\": \"<why>\"}. Put spec/research files only — no code paths. Run `python .trellis/scripts/get_context.py --mode packages` to list available specs. Delete this line once real entries are added."}

.trellis/tasks/05-20-05-20-skills-config-helper-extraction/design.md

@@ -0,0 +1,40 @@
+# design: config helper extraction
+
+## Scope
+
+本任务只扩展 `psutils` 的 config 公共 API，并把 skills 安装器切换到公共 API。公共 API 只处理通用配置对象访问，不处理路径、环境变量、平台选择或安装计划。
+
+## Public API
+
+复用既有 `ConvertTo-ConfigHashtable`，补强其输入兼容性：
+
+* `$null` -> 空 hashtable
+* `hashtable` -> 浅拷贝
+* `System.Collections.IDictionary` -> 遍历 keys 转成普通 hashtable
+* 其他对象 -> 遍历 `PSObject.Properties`
+
+新增 `Get-ConfigValue`：
+
+* 入参：`Values`、`Name`、`DefaultValue`
+* `Values` 类型：`hashtable`
+* key 匹配：`OrdinalIgnoreCase`
+* 返回：命中值或默认值，命中时不改变 value 类型
+
+## Data Flow
+
+`Install-Skills.ps1` 已导入 `psutils/modules/process.psm1`。本任务保留现有 `Import-SkillsConfigModule`，让它导入 `psutils/modules/config.psm1`，并在脚本初始化阶段或首次读取配置前确保公共 helper 可用。
+
+替换点：
+
+* `ConvertTo-SkillsHashtable` -> `ConvertTo-ConfigHashtable`
+* `Get-SkillsConfigValue` -> `Get-ConfigValue`
+
+## Compatibility
+
+`Install-Skills.ps1` 当前本地 helper 支持 `System.Collections.IDictionary`；`psutils` 现有 `ConvertTo-ConfigHashtable` 只处理 hashtable 和普通对象。因此需要先补强公共 helper，再替换调用方。
+
+`Get-ConfigValue` 的行为应与现有 skills helper 一致：仅 shallow lookup，不做 nested path，不做 key normalization，不修改 key 大小写。
+
+## Rollback
+
+若 downstream 行为异常，可恢复 `Install-Skills.ps1` 本地 helper，保留 `psutils` 新 helper；新 API 为向后兼容新增，不影响现有调用方。

.trellis/tasks/05-20-05-20-skills-config-helper-extraction/implement.jsonl

@@ -0,0 +1 @@
+{"_example": "Fill with {\"file\": \"<path>\", \"reason\": \"<why>\"}. Put spec/research files only — no code paths. Run `python .trellis/scripts/get_context.py --mode packages` to list available specs. Delete this line once real entries are added."}

.trellis/tasks/05-20-05-20-skills-config-helper-extraction/implement.md

@@ -0,0 +1,29 @@
+# implement: config helper extraction
+
+## Checklist
+
+1. 更新 `psutils/src/config/convert.ps1`
+   * 补强 `ConvertTo-ConfigHashtable` 对 `System.Collections.IDictionary` 的处理。
+   * 新增 `Get-ConfigValue`。
+   * 为新增/更新公共函数保留中文 comment-based help。
+2. 更新 `psutils/modules/config.psm1`
+   * 导出 `Get-ConfigValue`。
+3. 更新 `psutils/psutils.psd1`
+   * 在 `FunctionsToExport` 中加入 `Get-ConfigValue`。
+4. 更新 `psutils/tests/config.Tests.ps1`
+   * 添加/补充 helper 用例。
+5. 更新 `ai/skills/Install-Skills.ps1`
+   * 删除 `ConvertTo-SkillsHashtable` 和 `Get-SkillsConfigValue`。
+   * 确保在使用 helper 前导入 config 模块。
+   * 将调用点替换为公共函数。
+6. 更新 `tests/SkillsInstaller.Tests.ps1`
+   * 若导入时机改变导致测试需要调整，只做最小更新。
+7. 验证
+   * `pnpm exec pwsh -NoProfile -File ./scripts/pwsh/devops/Invoke-PesterMode.ps1 -Mode serial -Path ./psutils/tests/config.Tests.ps1`
+   * `pnpm exec pwsh -NoProfile -File ./scripts/pwsh/devops/Invoke-PesterMode.ps1 -Mode serial -Path ./tests/SkillsInstaller.Tests.ps1`
+   * `pnpm qa`
+   * `pnpm test:pwsh:all`
+
+## Review Gate
+
+确认本轮 diff 没有包含 path/env placeholder 实现，也没有把 skills 安装计划逻辑移入 `psutils`。

.trellis/tasks/05-20-05-20-skills-config-helper-extraction/prd.md

@@ -0,0 +1,29 @@
+# skills config helper extraction
+
+## Goal
+
+把多个 PowerShell 脚本重复实现的“配置对象转 hashtable”和“大小写不敏感读取配置值”收敛到 `psutils/modules/config.psm1`，先供 `ai/skills/Install-Skills.ps1` 使用。
+
+## Requirements
+
+* `psutils` 暴露稳定公共 helper，用于浅层配置对象转换与大小写不敏感键读取。
+* helper 必须保持通用配置语义，不包含 skills、ctx7、agent、GitHub release 等领域概念。
+* `ConvertTo-ConfigHashtable` 需要兼容 `hashtable`、`System.Collections.IDictionary`、`PSCustomObject`、`$null`。
+* 新增读取函数应支持默认值，并在 key 命中时保留原始 value 类型。
+* `Install-Skills.ps1` 应移除本地 `ConvertTo-SkillsHashtable` / `Get-SkillsConfigValue`，改用 `psutils` 公共 helper。
+* 本轮不抽 `Resolve-SkillsPath` / `Resolve-SkillsEnvPlaceholder`；路径/env placeholder 留给 `skills-config-path-placeholder-extraction` 子任务。
+* 本轮不拆 `Install-Skills.ps1` 私有业务模块；模块拆分留给 `skills-installer-private-module-split` 子任务。
+
+## Acceptance Criteria
+
+* [ ] `psutils/modules/config.psm1` 导出通用 config helper，函数有中文 comment-based help、参数说明和返回值说明。
+* [ ] `psutils/tests/config.Tests.ps1` 覆盖 dictionary 转换、大小写不敏感读取、默认值、原始类型保留。
+* [ ] `Install-Skills.ps1` 改用公共 helper 后行为不变。
+* [ ] 不把 skills 安装器领域语义加入 `psutils`。
+* [ ] 定向 config 测试、skills 安装器测试、`pnpm qa`、`pnpm test:pwsh:all` 通过。
+
+## Out of Scope
+
+* 配置路径解析、`~` 展开、`${VAR}` / `%VAR%` placeholder 展开。
+* GitHub CLI 安装器、rclone、start-container 的批量替换。
+* `Install-Skills.ps1` 业务模块拆分。

.trellis/tasks/05-20-05-20-skills-config-helper-extraction/task.json

@@ -0,0 +1,26 @@
+{
+  "id": "05-20-skills-config-helper-extraction",
+  "name": "05-20-skills-config-helper-extraction",
+  "title": "skills config helper extraction",
+  "description": "",
+  "status": "in_progress",
+  "dev_type": null,
+  "scope": null,
+  "package": null,
+  "priority": "P2",
+  "creator": "mudssky",
+  "assignee": "mudssky",
+  "createdAt": "2026-05-20",
+  "completedAt": null,
+  "branch": null,
+  "base_branch": "master",
+  "worktree_path": null,
+  "commit": null,
+  "pr_url": null,
+  "subtasks": [],
+  "children": [],
+  "parent": "05-20-skills-installer-config",
+  "relatedFiles": [],
+  "notes": "",
+  "meta": {}
+}

.trellis/tasks/05-20-skills-config-path-placeholder-extraction/check.jsonl

@@ -0,0 +1 @@
+{"_example": "Fill with {\"file\": \"<path>\", \"reason\": \"<why>\"}. Put spec/research files only — no code paths. Run `python .trellis/scripts/get_context.py --mode packages` to list available specs. Delete this line once real entries are added."}

.trellis/tasks/05-20-skills-config-path-placeholder-extraction/implement.jsonl

@@ -0,0 +1 @@
+{"_example": "Fill with {\"file\": \"<path>\", \"reason\": \"<why>\"}. Put spec/research files only — no code paths. Run `python .trellis/scripts/get_context.py --mode packages` to list available specs. Delete this line once real entries are added."}

.trellis/tasks/05-20-skills-config-path-placeholder-extraction/prd.md

@@ -0,0 +1,24 @@
+# skills config path placeholder extraction
+
+## Goal
+
+把多个脚本重复出现的配置路径解析和环境变量 placeholder 展开能力抽成通用基础设施，供后续 `Install-Skills.ps1`、GitHub CLI 安装器等脚本复用。
+
+## Requirements
+
+* 评估并设计通用 API，覆盖 `~`、相对 base path、`${VAR}`、`%VAR%` 这类配置路径展开场景。
+* API 必须只表达通用路径/env 解析语义，不包含 skills、GitHub release、rclone 等领域概念。
+* 缺失环境变量时必须有明确错误，避免路径静默落到错误目录。
+* 需要明确哪些脚本先接入，避免一次性批量改动过大。
+
+## Acceptance Criteria
+
+* [ ] 有独立 `design.md` 和 `implement.md` 描述 API、调用方迁移顺序和验证命令。
+* [ ] 通用 helper 有 Pester 测试覆盖 `~`、相对路径、`${VAR}`、缺失 env。
+* [ ] 首个调用方接入后行为不变。
+* [ ] 不和 config object helper 或 skills 私有模块拆分混在同一提交。
+
+## Out of Scope
+
+* 安装计划、agent 目录、ctx7 检测。
+* 大规模替换所有历史脚本。