@sokeai/cli 1.0.65 → 1.0.67

package/skills/ai-coach-director/references/role-resource-matching.md

@@ -0,0 +1,312 @@
+# Part2 平台资源自动匹配规则
+
+> 本节是 Part2 角色创建后自动执行的资源匹配流程。头像和语音不在 Part2 内容生成阶段预设，而是在角色落地后查询系统资源库自动匹配。
+>
+> **v2.0 升级**：匹配模式从"拉全量→文本匹配"升级为"提取角色性别/年龄特征→CLI 参数精准过滤→取结果"，利用 CLI 原生的 `--gender` / `--age-group` 服务端过滤能力，提升匹配精度和效率。
+
+## 资源匹配时机
+
+Part2 `replace_ai_roles` / `add_ai_role` apply 成功 → 立即执行资源匹配流程，不等待用户触发。
+
+---
+
+## 前置步骤：从角色卡提取性别与年龄
+
+在执行任何 CLI 查询之前，必须先从每个角色的 `role_data` 中提取性别和年龄段特征，映射为 CLI 参数：
+
+### 性别映射表（gender）
+
+| 角色描述中的特征词 | → gender |
+|---|---|
+| 男、先生、他、男士、男性、（男性名字：建国/振国/志强/伟等） | `male` |
+| 女、女士、她、太太、小姐、女性、（女性名字：芳/丽/敏/娟/婷等） | `female` |
+| 无明显性别特征 | 不传 `--gender` |
+
+> **提取优先级**：角色名称(.name) > 角色描述(.description) > 角色背景(.background) > MBTI+沟通风格交叉推断
+
+### 年龄段映射表（age_group）
+
+| 角色描述中的特征词 | → age_group |
+|---|---|
+| 青年、年轻、刚毕业、新手、25-35、初级、新入职、小张/小李等年轻称呼 | `youth` |
+| 中年、35-50、资深、经理、主管、部门负责人、有多年经验 | `middle-aged` |
+| 老年、50+、退休、资深专家、老前辈、临近退休、老张/老李等长辈称呼 | `senior` |
+| 无明显年龄特征 | 不传 `--age-group` |
+
+> **提取优先级**：角色背景(.background) > 角色描述(.description) > 角色名称(.name)
+
+---
+
+## 头像资源匹配
+
+### Step 1：CLI 精准过滤查询
+
+根据前置步骤提取的 `gender` 和 `age_group`，使用 CLI 过滤参数查询：
+
+```bash
+# 性别+年龄都明确 → 一阶精准查询
+soke-cli ai-training +list-role-avatars \
+  --gender <gender> \
+  --age-group <age_group> \
+  --lang zh \
+  --show-detail \
+  --pretty
+
+# 仅性别明确 → 仅按性别过滤
+soke-cli ai-training +list-role-avatars \
+  --gender <gender> \
+  --lang zh \
+  --show-detail \
+  --pretty
+
+# 特征信息不足 → 不传过滤参数
+soke-cli ai-training +list-role-avatars \
+  --lang zh \
+  --show-detail \
+  --pretty
+```
+
+### Step 2：从过滤结果中选最佳匹配
+
+CLI 返回的头像列表已经是服务端按 `sort` 排序的过滤结果。按以下优先级选取：
+
+| 优先级 | 匹配条件 | 选取规则 |
+|---|---|---|
+| P0 | 性别 + 年龄都吻合 | 取过滤结果中 `sort` 最小的第 1 条 |
+| P1 | 仅性别吻合（年龄无精确匹配） | 取 `--gender` 过滤结果的第 1 条 |
+| P2 | 仅年龄吻合（性别无精确匹配） | 取 `--age-group` 过滤结果的第 1 条 |
+| P3 | 性别年龄均无匹配 | 不传过滤参数，全量取第 1 条通用/中性头像，并标注「无精确匹配」 |
+
+> **降级链路**：一阶查询返回空 → 去掉 `--age-group`（仅性别）→ 仍空则去掉 `--gender`（仅年龄）→ 仍空则全量无过滤。每次降级记录一次。
+
+### Step 3：写入角色
+
+> ⚠️ **必须与语音资源合并写入**：头像和语音写入**同一个** `patch_ai_role` 操作，不可分两次。合并写入示例见文件末尾「合并写入模板」。
+
+使用 `patch_ai_role` 将匹配到的头像资源 URL 写入（与 voice_id 合并为单次操作）：
+
+```json
+[
+  {
+    "type": "patch_ai_role",
+    "data": {
+      "scenario_role_id": "<角色ID>",
+      "patch": {
+        "role_data": {
+          "avatar": "<头像资源URL>"
+        },
+        "customized_fields": ["avatar"]
+      }
+    }
+  }
+]
+```
+
+> ⚠️ `avatar` 字段传入头像资源 **URL**（如 `https://newsokeeditorcdn.soke.cn/public/ai/avatars/business_owner_female.png`），来自 `+list-role-avatars` 返回的 `url` 字段，**不能**传资源 `id`。
+> ⚠️ `patch` 中必须包含 `customized_fields`，指明被修改的字段，否则平台可能不识别该更新。
+
+匹配结果在聊天中只显示一行摘要（如「张总 → 威严中年男性头像」），不展示原始 JSON。
+
+---
+
+## 语音资源匹配
+
+### Step 1：CLI 精准过滤查询
+
+```bash
+# 性别+年龄都明确 → 一阶精准查询
+soke-cli ai-training +list-role-voices \
+  --gender <gender> \
+  --age-group <age_group> \
+  --lang zh \
+  --pretty
+
+# 降级查询（同头像降级链路）
+```
+
+### Step 2：从过滤结果中选最佳匹配
+
+| 优先级 | 匹配条件 | 选取规则 |
+|---|---|---|
+| P0 | 性别 + 年龄都吻合 | 取过滤结果的第 1 条 |
+| P1 | 仅性别吻合 | 取 `--gender` 过滤结果的第 1 条 |
+| P2 | 仅年龄吻合 | 取 `--age-group` 过滤结果的第 1 条 |
+| P3 | 性别年龄均无匹配 | 全量取第 1 条通用默认音色，标注「无精确匹配」 |
+
+> **降级链路**：同头像匹配——一阶→去年龄→去性别→全量。每次降级记录一次。
+
+### Step 3：写入角色
+
+> ⚠️ **必须与头像资源合并写入**：语音和头像写入**同一个** `patch_ai_role` 操作，不可分两次。合并写入示例见文件末尾「合并写入模板」。
+
+使用 `patch_ai_role` 将匹配到的语音资源 ID 写入（与 avatar 合并为单次操作）：
+
+```json
+[
+  {
+    "type": "patch_ai_role",
+    "data": {
+      "scenario_role_id": "<角色ID>",
+      "patch": {
+        "role_data": {
+          "voice_id": "<语音资源ID>"
+        },
+        "customized_fields": ["voice_id"]
+      }
+    }
+  }
+]
+```
+
+> ⚠️ `voice_id` 传入声音资源 **ID**（如 `zh_female_warm_01`），来自 `+list-role-voices` 返回的 `id` 字段，**不能**传 `sample_url` 或名称字符串。
+> ⚠️ `patch` 中必须包含 `customized_fields`，指明被修改的字段。
+
+匹配结果在聊天中只显示一行摘要（如「张总 → 沉稳中年男声」）。
+
+---
+
+## 完整流程时序
+
+```
+Part2 角色 apply 成功
+  → 提取角色性别(gender) + 年龄(age_group)
+  → CLI 并行精准过滤查询:
+      +list-role-avatars --gender <g> --age-group <a> --lang zh --show-detail --pretty
+      +list-role-voices --gender <g> --age-group <a> --lang zh --pretty
+    → 任一返回空则降级（去年龄→去性别→全量）
+  → ⚠️ 单次 patch_ai_role 合并写入 avatar + voice_id（customized_fields: ["avatar", "voice_id"]）
+  → ⚠️ get-scenario 强制验证 avatar 非空 URL + voice_id 非空 ID
+  → 验证失败 → 重新读取 updated_at → 重试 1 次
+  → 仍失败 → 标注「资源匹配未完成」，不阻断后续 Part
+  → 资源匹配完成后，再进入 Part3
+```
+
+> **头像/语音的 patch 操作用同一个 idempotency_key**（如 `cli-<scenario_short>-part2-resources`），avatar 和 voice_id 放在同一个 `patch_ai_role` 的 `patch.role_data` 中，`customized_fields` 写 `["avatar", "voice_id"]`。**禁止分两次 patch**——分开调用会导致 updated_at 竞态。
+
+---
+
+## 端到端示例
+
+角色卡摘要：
+- 名称：谨慎型小微企业主
+- 描述：经营农资批发门店的女性老板，40多岁，关注融资成本和审批速度。
+- 背景：经营农资批发门店十余年，旺季前需短期周转资金 30-50 万……
+
+### 特征提取
+
+| 特征 | 来源字段 | 提取结果 | CLI 参数 |
+|---|---|---|---|
+| 性别 | 描述中"女性" | female | `--gender female` |
+| 年龄 | 描述中"40多岁"、背景中"十余年" | middle-aged | `--age-group middle-aged` |
+
+### CLI 查询
+
+```bash
+# 头像
+soke-cli ai-training +list-role-avatars \
+  --gender female \
+  --age-group middle-aged \
+  --lang zh \
+  --show-detail \
+  --pretty
+
+# 声音
+soke-cli ai-training +list-role-voices \
+  --gender female \
+  --age-group middle-aged \
+  --lang zh \
+  --pretty
+```
+
+### 写入
+
+```json
+{
+  "role_data": {
+    "avatar": "https://newsokeeditorcdn.soke.cn/public/ai/avatars/business_owner_female.png",
+    "voice_id": "zh_female_warm_01"
+  }
+}
+```
+
+---
+
+## 异常处理
+
+| 情况 | 处理 |
+|---|---|
+| 头像/语音库 CLI 查询失败（网络/权限） | 跳过资源匹配，标注「资源匹配未完成」，Part3 不受影响 |
+| 角色特征信息不足（无性别/年龄暗示） | 不传过滤参数，全量查询取第 1 条默认头像 + 默认音色，不标注匹配摘要 |
+| 过滤查询返回空 → 降级后仍空 | 全量查询取第 1 条，标注「无精确匹配，已使用默认资源」 |
+| patch_ai_role 失败 | 重新读取 updated_at 后重试 1 次；仍失败则标注，不阻断 Part3 |
+| patch_ai_role 返回成功但 avatar/voice_id 验证为空 | 重新读取 updated_at 后重试 1 次；仍失败则标注，不阻断 Part3 |
+
+---
+
+## 合并写入模板
+
+> ⚠️ **强制规则**：头像和语音必须合并为**单次** `patch_ai_role` 操作写入。禁止分两次 patch——分两次调用会导致第二次 patch 后 `updated_at` 变化，后续验收时可能误判第一次写入丢失。
+
+### operations JSON 结构
+
+```json
+[
+  {
+    "type": "patch_ai_role",
+    "data": {
+      "scenario_role_id": "<角色ID>",
+      "patch": {
+        "role_data": {
+          "avatar": "<头像资源URL>",
+          "voice_id": "<语音资源ID>"
+        },
+        "customized_fields": ["avatar", "voice_id"]
+      }
+    }
+  }
+]
+```
+
+### 完整 CLI 命令序列
+
+```bash
+# 1. 读取最新场景状态
+soke-cli ai-training +get-scenario \
+  --scenario-id <scenario_id> \
+  --pretty
+
+# 2. 写入合并的 operations JSON（Python json.dump）
+
+# 3. 预览
+soke-cli ai-training +preview-scenario-update \
+  --scenario-id <scenario_id> \
+  --base-updated-at <updated_at> \
+  --operations-file ./part2-resources.json \
+  --reason "Part2: 头像声音资源回填" \
+  --pretty
+
+# 4. 应用
+soke-cli ai-training +apply-scenario-update \
+  --scenario-id <scenario_id> \
+  --base-updated-at <updated_at> \
+  --operations-file ./part2-resources.json \
+  --idempotency-key "cli-<scenario_short>-part2-resources" \
+  --reason "Part2: 头像声音资源回填" \
+  --pretty
+
+# 5. 强制验证
+soke-cli ai-training +get-scenario \
+  --scenario-id <scenario_id> \
+  --pretty
+# 检查每个角色的 avatar 为非空 URL、voice_id 为非空 ID
+```
+
+### 验证失败重试
+
+```bash
+# 验证失败 → 重新读取 updated_at
+soke-cli ai-training +get-scenario --scenario-id <scenario_id> --pretty
+
+# 重新生成 patch → 重新 preview + apply（新 idempotency_key）
+# 仍失败 → 标注并继续 Part3
+```

package/skills/ai-coach-director/references/self-improvement-examples.md

@@ -0,0 +1,374 @@
+# Entry Examples
+
+Concrete examples of well-formatted entries with all fields.
+
+## Learning: Correction
+
+```markdown
+## [LRN-20250115-001] correction
+
+**Logged**: 2025-01-15T10:30:00Z
+**Priority**: high
+**Status**: pending
+**Area**: tests
+
+### Summary
+Incorrectly assumed pytest fixtures are scoped to function by default
+
+### Details
+When writing test fixtures, I assumed all fixtures were function-scoped. 
+User corrected that while function scope is the default, the codebase 
+convention uses module-scoped fixtures for database connections to 
+improve test performance.
+
+### Suggested Action
+When creating fixtures that involve expensive setup (DB, network), 
+check existing fixtures for scope patterns before defaulting to function scope.
+
+### Metadata
+- Source: user_feedback
+- Related Files: tests/conftest.py
+- Tags: pytest, testing, fixtures
+
+---
+```
+
+## Learning: Knowledge Gap (Resolved)
+
+```markdown
+## [LRN-20250115-002] knowledge_gap
+
+**Logged**: 2025-01-15T14:22:00Z
+**Priority**: medium
+**Status**: resolved
+**Area**: config
+
+### Summary
+Project uses pnpm not npm for package management
+
+### Details
+Attempted to run `npm install` but project uses pnpm workspaces.
+Lock file is `pnpm-lock.yaml`, not `package-lock.json`.
+
+### Suggested Action
+Check for `pnpm-lock.yaml` or `pnpm-workspace.yaml` before assuming npm.
+Use `pnpm install` for this project.
+
+### Metadata
+- Source: error
+- Related Files: pnpm-lock.yaml, pnpm-workspace.yaml
+- Tags: package-manager, pnpm, setup
+
+### Resolution
+- **Resolved**: 2025-01-15T14:30:00Z
+- **Commit/PR**: N/A - knowledge update
+- **Notes**: Added to CLAUDE.md for future reference
+
+---
+```
+
+## Learning: Promoted to CLAUDE.md
+
+```markdown
+## [LRN-20250115-003] best_practice
+
+**Logged**: 2025-01-15T16:00:00Z
+**Priority**: high
+**Status**: promoted
+**Promoted**: CLAUDE.md
+**Area**: backend
+
+### Summary
+API responses must include correlation ID from request headers
+
+### Details
+All API responses should echo back the X-Correlation-ID header from 
+the request. This is required for distributed tracing. Responses 
+without this header break the observability pipeline.
+
+### Suggested Action
+Always include correlation ID passthrough in API handlers.
+
+### Metadata
+- Source: user_feedback
+- Related Files: src/middleware/correlation.ts
+- Tags: api, observability, tracing
+
+---
+```
+
+## Learning: Promoted to AGENTS.md
+
+```markdown
+## [LRN-20250116-001] best_practice
+
+**Logged**: 2025-01-16T09:00:00Z
+**Priority**: high
+**Status**: promoted
+**Promoted**: AGENTS.md
+**Area**: backend
+
+### Summary
+Must regenerate API client after OpenAPI spec changes
+
+### Details
+When modifying API endpoints, the TypeScript client must be regenerated.
+Forgetting this causes type mismatches that only appear at runtime.
+The generate script also runs validation.
+
+### Suggested Action
+Add to agent workflow: after any API changes, run `pnpm run generate:api`.
+
+### Metadata
+- Source: error
+- Related Files: openapi.yaml, src/client/api.ts
+- Tags: api, codegen, typescript
+
+---
+```
+
+## Error Entry
+
+```markdown
+## [ERR-20250115-A3F] docker_build
+
+**Logged**: 2025-01-15T09:15:00Z
+**Priority**: high
+**Status**: pending
+**Area**: infra
+
+### Summary
+Docker build fails on M1 Mac due to platform mismatch
+
+### Error
+```
+error: failed to solve: python:3.11-slim: no match for platform linux/arm64
+```
+
+### Context
+- Command: `docker build -t myapp .`
+- Dockerfile uses `FROM python:3.11-slim`
+- Running on Apple Silicon (M1/M2)
+
+### Suggested Fix
+Add platform flag: `docker build --platform linux/amd64 -t myapp .`
+Or update Dockerfile: `FROM --platform=linux/amd64 python:3.11-slim`
+
+### Metadata
+- Reproducible: yes
+- Related Files: Dockerfile
+
+---
+```
+
+## Error Entry: Recurring Issue
+
+```markdown
+## [ERR-20250120-B2C] api_timeout
+
+**Logged**: 2025-01-20T11:30:00Z
+**Priority**: critical
+**Status**: pending
+**Area**: backend
+
+### Summary
+Third-party payment API timeout during checkout
+
+### Error
+```
+TimeoutError: Request to payments.example.com timed out after 30000ms
+```
+
+### Context
+- Command: POST /api/checkout
+- Timeout set to 30s
+- Occurs during peak hours (lunch, evening)
+
+### Suggested Fix
+Implement retry with exponential backoff. Consider circuit breaker pattern.
+
+### Metadata
+- Reproducible: yes (during peak hours)
+- Related Files: src/services/payment.ts
+- See Also: ERR-20250115-X1Y, ERR-20250118-Z3W
+
+---
+```
+
+## Feature Request
+
+```markdown
+## [FEAT-20250115-001] export_to_csv
+
+**Logged**: 2025-01-15T16:45:00Z
+**Priority**: medium
+**Status**: pending
+**Area**: backend
+
+### Requested Capability
+Export analysis results to CSV format
+
+### User Context
+User runs weekly reports and needs to share results with non-technical 
+stakeholders in Excel. Currently copies output manually.
+
+### Complexity Estimate
+simple
+
+### Suggested Implementation
+Add `--output csv` flag to the analyze command. Use standard csv module.
+Could extend existing `--output json` pattern.
+
+### Metadata
+- Frequency: recurring
+- Related Features: analyze command, json output
+
+---
+```
+
+## Feature Request: Resolved
+
+```markdown
+## [FEAT-20250110-002] dark_mode
+
+**Logged**: 2025-01-10T14:00:00Z
+**Priority**: low
+**Status**: resolved
+**Area**: frontend
+
+### Requested Capability
+Dark mode support for the dashboard
+
+### User Context
+User works late hours and finds the bright interface straining.
+Several other users have mentioned this informally.
+
+### Complexity Estimate
+medium
+
+### Suggested Implementation
+Use CSS variables for colors. Add toggle in user settings.
+Consider system preference detection.
+
+### Metadata
+- Frequency: recurring
+- Related Features: user settings, theme system
+
+### Resolution
+- **Resolved**: 2025-01-18T16:00:00Z
+- **Commit/PR**: #142
+- **Notes**: Implemented with system preference detection and manual toggle
+
+---
+```
+
+## Learning: Promoted to Skill
+
+```markdown
+## [LRN-20250118-001] best_practice
+
+**Logged**: 2025-01-18T11:00:00Z
+**Priority**: high
+**Status**: promoted_to_skill
+**Skill-Path**: skills/docker-m1-fixes
+**Area**: infra
+
+### Summary
+Docker build fails on Apple Silicon due to platform mismatch
+
+### Details
+When building Docker images on M1/M2 Macs, the build fails because
+the base image doesn't have an ARM64 variant. This is a common issue
+that affects many developers.
+
+### Suggested Action
+Add `--platform linux/amd64` to docker build command, or use
+`FROM --platform=linux/amd64` in Dockerfile.
+
+### Metadata
+- Source: error
+- Related Files: Dockerfile
+- Tags: docker, arm64, m1, apple-silicon
+- See Also: ERR-20250115-A3F, ERR-20250117-B2D
+
+---
+```
+
+## Extracted Skill Example
+
+When the above learning is extracted as a skill, it becomes:
+
+**File**: `skills/docker-m1-fixes/SKILL.md`
+
+```markdown
+---
+name: docker-m1-fixes
+description: "Fixes Docker build failures on Apple Silicon (M1/M2). Use when docker build fails with platform mismatch errors."
+---
+
+# Docker M1 Fixes
+
+Solutions for Docker build issues on Apple Silicon Macs.
+
+## Quick Reference
+
+| Error | Fix |
+|-------|-----|
+| `no match for platform linux/arm64` | Add `--platform linux/amd64` to build |
+| Image runs but crashes | Use emulation or find ARM-compatible base |
+
+## The Problem
+
+Many Docker base images don't have ARM64 variants. When building on
+Apple Silicon (M1/M2/M3), Docker attempts to pull ARM64 images by
+default, causing platform mismatch errors.
+
+## Solutions
+
+### Option 1: Build Flag (Recommended)
+
+Add platform flag to your build command:
+
+\`\`\`bash
+docker build --platform linux/amd64 -t myapp .
+\`\`\`
+
+### Option 2: Dockerfile Modification
+
+Specify platform in the FROM instruction:
+
+\`\`\`dockerfile
+FROM --platform=linux/amd64 python:3.11-slim
+\`\`\`
+
+### Option 3: Docker Compose
+
+Add platform to your service:
+
+\`\`\`yaml
+services:
+  app:
+    platform: linux/amd64
+    build: .
+\`\`\`
+
+## Trade-offs
+
+| Approach | Pros | Cons |
+|----------|------|------|
+| Build flag | No file changes | Must remember flag |
+| Dockerfile | Explicit, versioned | Affects all builds |
+| Compose | Convenient for dev | Requires compose |
+
+## Performance Note
+
+Running AMD64 images on ARM64 uses Rosetta 2 emulation. This works
+for development but may be slower. For production, find ARM-native
+alternatives when possible.
+
+## Source
+
+- Learning ID: LRN-20250118-001
+- Category: best_practice
+- Extraction Date: 2025-01-18
+```