@comate/zulu 1.2.1-beta.1 → 1.3.0

package/comate-engine/assets/skills/icafe-comate/references/platform-concepts.md

@@ -0,0 +1,317 @@
+# iCafe 平台概念指南
+
+## 概述
+
+iCafe 是百度内部的项目管理和敏捷研发平台，类似于 Jira。本文档介绍 iCafe 的核心概念。
+
+官网: `https://console.cloud.baidu-int.com/devops/icafe`
+
+---
+
+## 空间 (Space)
+
+空间是 iCafe 的项目容器，是组织卡片和计划的基本单元。
+
+### 关键属性
+
+| 属性 | 说明 | 示例 |
+|------|------|------|
+| `id` | 内部数字 ID | `12345` |
+| `name` | 空间名称 | `我的项目` |
+| `prefixCode` | 空间标识 (prefixCode)，CLI 中 `--space` 参数的值 | `myspace` |
+
+### JSON 响应示例
+
+```json
+{ "id": 87531, "name": "Dodo", "prefixCode": "dododododoit" }
+```
+
+### 重要说明
+
+- CLI 中所有 `--space` 参数使用 `prefixCode`，不是数字 `id`
+- 可通过 `icafe-cli space latest` 获取用户最近访问的空间列表
+- 空间树 (`icafe-cli space tree`) 可查看完整的空间层级结构
+
+---
+
+## 卡片 (Card / Issue)
+
+卡片是 iCafe 的核心工作单元，代表一个具体的任务、需求或缺陷。
+
+### 标识符
+
+| 标识符 | 说明 | 在哪使用 |
+|--------|------|----------|
+| `sequence` | 序列号，空间内自增整数，人类可读 | URL、CLI 命令的 `--sequence` |
+| `issueId` | 内部数据库 ID | 仅内部使用，不要用于 CLI |
+
+### 卡片关键字段
+
+| 字段 | 说明 |
+|------|------|
+| `sequence` | 卡片编号（整数，空间内唯一） |
+| `title` | 标题 |
+| `type.name` | 卡片类型（Epic / Story / Task / Bug） |
+| `status` | 当前流程状态 |
+| `responsiblePeople` | 负责人列表（含 username、name） |
+| `createdUser` | 创建人 |
+| `createdTime` | 创建时间，格式 `yyyy-MM-dd HH:mm:ss` |
+| `lastModifiedTime` | 最近修改时间 |
+| `detail` | 描述，HTML 富文本 |
+| `parent` | 父卡片引用（含 sequence、title） |
+| `properties` | 自定义属性列表（见下方"自定义属性"章节） |
+| `isFinishedStatus` | 是否已完结状态（布尔值） |
+
+### 卡片类型
+
+| 类型 | 说明 | 典型用途 |
+|------|------|---------|
+| `Epic` | 史诗 | 大型功能模块，包含多个 Story |
+| `Story` | 用户故事 | 一个完整的功能需求 |
+| `Task` | 任务 | 技术任务、子任务、杂项工作 |
+| `Bug` | 缺陷 | 功能异常、线上问题 |
+
+> **注意**: 类型名称在 IQL 查询中区分大小写，使用英文原名。每个空间可以自定义卡片类型与名称，通过 `icafe-cli space issue-types` 查询。
+
+### 卡片 URL 格式
+
+```
+https://console.cloud.baidu-int.com/devops/icafe/issue/{space}-{sequence}/show
+```
+
+例如: `https://console.cloud.baidu-int.com/devops/icafe/issue/myspace-1001/show`
+
+---
+
+## 流程状态 (Workflow Status)
+
+卡片的生命周期通过流程状态管理。状态有定义好的流转规则。
+
+### 常见状态流转
+
+```
+新建 → 待开发 → 开发中 → 开发完成 → 测试中 → 已完成
+```
+
+### 常见状态
+
+| 状态 | 说明 |
+|------|------|
+| `新建` | 刚创建的卡片 |
+| `待开发` | 等待开发 |
+| `开发中` | 正在开发 |
+| `进行中` | 正在进行 |
+| `待测试` | 等待测试 |
+| `测试中` | 正在测试 |
+| `已完成` | 开发完成 |
+| `已关闭` | 卡片关闭 |
+
+### 状态流转规则
+
+- 状态有顺序，支持 IQL 中的比较操作 (`>=`, `<=`)
+- `isFinishedStatus: true` 表示该卡片处于终态
+- 默认情况下，更新状态时会检查流转规则 (`isCheckStatus=true`)
+- 使用 `--no-check-status` 可跳过检查，强制设置任意状态
+- **查询时不要假设状态名称**，先通过 `space type-statuses` 确认该类型的合法状态列表
+
+---
+
+## 优先级 (Priority)
+
+卡片的紧急程度，使用标准的 5 级优先级:
+
+| 优先级 | 含义 |
+|--------|------|
+| `P0-Highest` | 最高优先级，紧急 |
+| `P1-High` | 高优先级 |
+| `P2-Middle` | 中等优先级 |
+| `P3-Low` | 低优先级 |
+| `P4-Lowest` | 最低优先级 |
+
+> **注意**: 部分空间可能使用 `P2-Medium` 而非 `P2-Middle`，以 `space type-fields` 返回的值为准。
+
+---
+
+## 计划 (Plan)
+
+计划是 iCafe 中的迭代/版本管理单元。
+
+### 关键属性
+
+| 属性 | 说明 |
+|------|------|
+| `id` | 计划 ID |
+| `name` | 计划名称 |
+| `path` | 计划路径 (层级路径) |
+| `parentId` | 父计划 ID |
+| `status` | 计划状态 (`ACTIVE` 或 `ARCHIVED`) |
+| `startDate` | 开始日期 |
+| `endDate` | 结束日期 |
+
+### JSON 响应示例
+
+```json
+{ "id": 1107361, "name": "03.02~03.08", "path": "2026Q1/03.02~03.08", "status": "ACTIVE" }
+```
+
+### 层级结构
+
+计划支持层级嵌套，通过路径表示:
+- 顶级计划: `2024Q1`
+- 子计划: `2024Q1/Sprint1`
+- 孙计划: `2024Q1/Sprint1/Week1`
+
+在 IQL 中使用 `所属计划` 字段查询时，需要使用完整路径。
+
+---
+
+## 自定义属性 (Properties)
+
+每张卡片包含一组 `properties`，内容因空间和卡片类型而异。
+
+### Properties 数据结构
+
+```json
+{
+  "fieldType": "SELECT_LIST",
+  "localId": 22797,
+  "propertyName": "优先级",
+  "displayValue": "P0-Highest",
+  "value": "17185"
+}
+```
+
+- `fieldType`: 字段类型 (SELECT_LIST, USER_PICKER, DATE_TIME, NUMBER_FIELD 等)
+- `localId`: 字段内部 ID
+- `propertyName`: 字段中文名称 (用于 `--fields` 参数和 IQL 查询)
+- `displayValue`: 人类可读的展示值
+- `value`: 内部存储值 (更新时可以使用 displayValue)
+
+### 常见属性字段
+
+以下是各空间中常见的自定义属性 (不同空间可能有所不同，以 `space type-fields` 返回为准):
+
+| 属性名 | fieldType | 说明 |
+|--------|-----------|------|
+| 优先级 | SELECT_LIST | P0-Highest / P1-High / P2-Middle / P3-Low / P4-Lowest |
+| 所属计划 | PLAN_BOX | 关联的迭代计划 |
+| 所属项目 | PROJECT_MANAGEMENT | 关联项目 |
+| 截止日期 | DATE_TIME | 卡片截止时间 |
+| 计划上线日期 | DATE_TIME | 预计上线时间 |
+| 实际上线日期 | DATE_TIME | 实际上线时间 |
+| 估算工时 | NUMBER_FIELD | 预估研发工时 (小时) |
+| 实际工时 | NUMBER_FIELD | 实际花费工时 |
+| RD负责人 | USER_PICKER | 研发负责人 |
+| FE负责人 | USER_PICKER | 前端负责人 |
+| QA负责人 | USER_PICKER | 测试负责人 |
+| PM负责人 | USER_PICKER | 产品负责人 |
+| 关注人 | USER_PICKER | 卡片关注人 |
+| 是否免测 | SELECT_LIST | 是/否 |
+| Severity | SELECT_LIST | Bug 严重程度 (S1/S2/S3/S4) |
+| Bug根因 | SELECT_LIST | Bug 根本原因分类 |
+| 线上问题级别 | SELECT_LIST | P0/P1/P2/P3 |
+
+### 系统字段
+
+以下字段通过专用参数 (`--title`, `--assignee` 等) 或 `--fields` 中文名更新:
+
+| 字段名 (中文) | 说明 |
+|---------------|------|
+| `标题` | 卡片标题 |
+| `内容` | 卡片描述 (HTML 格式) |
+| `类型` | 卡片类型 |
+| `负责人` | 负责人用户名 |
+| `流程状态` | 当前流程状态 |
+| `优先级` | 优先级等级 |
+| `创建人` | 创建者用户名 |
+| `创建时间` | 创建时间 |
+| `更新时间` | 最后更新时间 |
+| `截止日期` | 截止日期 |
+| `所属计划` | 关联的计划 |
+| `标签` | 卡片标签 |
+
+> **操作约束**: 通用属性 (状态、负责人、优先级等) 通过 `--status`、`--assignee`、`--priority` 参数直接设置；自定义属性通过 `--fields "属性名=值"` 更新。
+
+---
+
+## 研发数据链 (DevInfo)
+
+研发数据链记录卡片从代码到上线的完整研发活动。
+
+### 数据类型
+
+| 类型 | 说明 | 包含信息 |
+|------|------|----------|
+| `codeReview` | 代码评审 | 评审 ID、URL、状态 (MERGED/PASSED)、提交人、changeId |
+| `codeMerge` | 代码合并 | Git 提交记录、分支信息、流水线构建状态 |
+| `releaseInfo` | 发布信息 | 版本号、敏捷流水线 URL |
+| `initiateTest` | 提测记录 | 测试阶段信息 |
+| `passTest` | 测试通过 | 测试通过记录 |
+| `deploy` | 部署 | 部署 Job URL、环境信息 |
+
+### codeMerge JSON 示例
+
+```json
+{
+  "branch": "master",
+  "commitId": "c8f0b1a89e316502e9f892f2754baef414dc0b86",
+  "commitMessage": "dododododoit-5 前端增加routes和links",
+  "commitTime": "Mar 11, 2026 4:51:51 PM",
+  "projectName": "baidu/bapi/dodo",
+  "changeUrl": "http://icode.baidu.com/myreview/changes/c/baidu/bapi/dodo/+/120034262",
+  "pipeLineCommit": {
+    "pipelineId": 244154168,
+    "pipeLineUrl": "http://agile.baidu.com//#/detail/244154168/job/0",
+    "status": "SUCC"
+  }
+}
+```
+
+---
+
+## 用户标识
+
+iCafe 使用百度内部用户名标识用户:
+- 正式员工: 如 `zhangsan`
+- 外包员工: 通常以 `v_` 开头，如 `v_liuxiang`
+
+在 IQL 中可以使用 `currentUser` 表示当前认证用户。
+
+---
+
+## 评论 (Comment)
+
+卡片上的讨论和记录信息。每条评论包含:
+- `id`: 评论 ID
+- `content`: 评论内容
+- `username`: 创建人用户名
+- `chineseName`: 创建人中文名
+- `createTime`: 创建时间
+- `isDeleted`: 是否已删除
+- `parentCommentId`: 父评论 ID (回复场景)
+
+---
+
+## IQL 关键约束
+
+详细语法见 `references/iql-syntax.md`，以下是使用时的关键注意事项:
+
+1. **字段名使用中文**: IQL 中所有字段名均为中文 (`类型`、`负责人`、`流程状态` 等)
+2. **日期不支持 `>=`/`<=`**: 日期字段只支持 `>` 和 `<`，需要范围时用 AND 组合
+3. **`currentUser` 魔法变量**: 表示当前登录用户，可用于 `负责人 = currentUser`
+4. **状态顺序比较**: `流程状态 <= 开发中` 会匹配所有顺序在"开发中"之前 (含) 的状态
+5. **计划路径需完整**: `所属计划 = "2026Q1/03.02~03.08"`，不能只写叶子节点名
+6. **字符串值可不加引号**: 但含空格或特殊字符时必须加引号
+7. **不要猜测状态值**: 不同空间的状态配置不同，应先通过查询确认可用状态
+
+---
+
+## 重要约束与最佳实践
+
+1. **`--space` 必须使用 prefixCode** (如 `myspace`)，不是数字 id
+2. **`--sequence` 是空间内自增序号**，不是全局唯一 id
+3. **描述和评论字段必须是 HTML**，不能直接传 Markdown (详见 SKILL.md 转换规则)
+4. **批量查询 devinfo 最多 100 张卡片** (`--sequences` 逗号分隔)
+5. **批量查询 history/changes 最多 50 张卡片**
+6. **查询结果默认不含子卡片**，需要时加 `--show-children`
+7. **优先级格式含数字前缀**: `P0-Highest`、`P1-High`、`P2-Middle`、`P3-Low`、`P4-Lowest`

package/comate-engine/assets/skills/icafe-comate/references/smart-create-workflow.md

@@ -0,0 +1,171 @@
+# 智能建卡工作流
+
+当用户需要创建卡片但没有提供完整的空间、类型等信息时，使用本流程智能推断并创建。
+
+---
+
+## 适用场景
+
+- 用户说"帮我建个卡片记录一下"
+- 用户说"创建一个 Bug"但没说哪个空间
+- 用户说"在 cloud-iCafe 建个卡片"但没说类型
+- 任何需要新建卡片但信息不完整的场景
+
+## 第一步：确定空间
+
+**1.1 用户明确指定了空间** → 直接使用
+
+**1.2 从上下文推断**
+
+如果用户没指定空间，调 smart-find 获取用户活跃空间：
+
+```bash
+icafe-cli card smart-find
+```
+
+从 `stats.bySpace` 推断空间：
+- 只有 1 个空间 → 直接使用
+- 有多个空间 → 结合以下信号选择：
+  - 用户描述中的关键词与空间名/卡片标题匹配
+  - 如果在 git 仓库中，`git remote get-url origin` 提取仓库关键词与空间匹配
+  - `stats.bySpace[0]` 是最活跃的空间，优先推荐
+- 无法确定 → 列出候选空间（附卡片数量），让用户选择
+
+**1.3 无任何线索** → 必须询问用户
+
+## 第二步：确定类型
+
+按以下优先级，**多个信号综合判断**：
+
+**2.1 用户明确指定了类型** (如"建个 Bug") → 直接使用
+
+**2.2 smart-find 该空间的类型分布**
+
+直接读 `stats.bySpaceType`（已按数量降序排列）：
+```
+例如: [{"space":"cloud-iCafe", "type":"Task", "count":8},
+       {"space":"cloud-iCafe", "type":"Story", "count":4}]
+→ 该空间最常用 Task
+```
+
+**2.3 用户描述关键词**
+
+| 关键词 | 推断类型 |
+|--------|---------|
+| "修复", "fix", "bug", "缺陷", "问题" | Bug |
+| "新增", "功能", "需求", "feature" | Story/Feature |
+| "任务", "task", "优化", "重构" | Task |
+| "史诗", "大需求", "epic" | Epic |
+
+**2.4 git 分支名模式**（如果在 git 仓库中）
+
+```bash
+git rev-parse --abbrev-ref HEAD
+```
+
+| 分支名模式 | 推断类型 |
+|-----------|---------|
+| `bugfix/*`, `fix/*`, `hotfix/*` | Bug |
+| `feature/*`, `feat/*` | Story/Feature |
+| `task/*`, `chore/*`, `docs/*` | Task |
+
+**2.5 综合决策**
+
+```
+最终类型 =
+  用户指定 (最高优先)
+  > smart-find 该空间最常用类型 + 用户关键词交叉验证
+  > 分支名模式推断
+  > 单独的 smart-find 最常用类型
+```
+
+至少两个信号指向同一类型 → 自动使用并告知用户。
+只有一个信号或信号冲突 → 推荐但让用户确认。
+无信号 → 询问用户，可用 `space issue-types` 列出选项。
+
+> **避免重复调用**: 如果确定了类型后紧接着要调 `space type-fields`，不需要先调 `issue-types` 确认类型。`type-fields` 调用成功即隐含类型存在的验证。
+
+## 第三步：获取字段信息
+
+```bash
+icafe-cli space type-fields --space <space> --type <type>
+```
+
+关注：
+- **优先级字段**: 有则用默认值（如 `P2-Middle`），无此字段则不传
+- **必填字段**: 尽量填充，但 API 不强制校验自定义必填字段，不必因此阻塞创建
+- **字段可选值**: 选择类字段的值必须从 `valueItems` 中取
+
+## 第四步：填充信息并创建
+
+| 字段 | 来源 |
+|------|------|
+| 标题 (title) | 用户提供，或从用户描述中提取 |
+| 正文 (detail) | 用户提供的详细描述，转 HTML。不确定可不传（使用模板默认值）|
+| 类型 (type) | 第二步确定 |
+| 负责人 (assignee) | 不传时 CLI 自动填充当前用户 |
+| 优先级 (priority) | 从 type-fields 获取选项动态选择，不能硬编码 |
+| 自定义字段 (fields) | 从 type-fields 获取必填项，尽量填充 |
+
+```bash
+icafe-cli card create \
+  --space <space> \
+  --title "用户提供或推断的标题" \
+  --type <type> \
+  --priority <从 type-fields 获取的值> \
+  --fields "自定义字段1=值1,自定义字段2=值2"
+```
+
+**创建前向用户确认**：汇总空间、类型、标题等信息，确认后再执行。
+
+## 第五步：返回结果
+
+创建成功后返回：
+- **卡片序列号**: 从返回的 `issues[0].sequence` 获取
+- **卡片 URL**: `issues[0].url` 或拼接 `https://console.cloud.baidu-int.com/devops/icafe/issue/{space}-{sequence}/show`
+- **卡片信息摘要**: 空间、序列号、标题、类型
+
+> **注意**: OpenAPI 创建接口只返回基本信息（sequence, title, url），不返回完整卡片详情。如需确认自动分配的状态、负责人等，创建后再调 `card get --brief`。
+
+## 决策流程图
+
+```
+用户要创建卡片
+  │
+  ├─ 1. 确定空间
+  │   ├─ 用户指定？ → 直接用
+  │   ├─ card smart-find → stats.bySpace
+  │   │   ├─ 1 个空间 → 直接用
+  │   │   ├─ 多个 → 关键词匹配/git remote 匹配 → 推荐或让用户选
+  │   │   └─ 无结果 → 问用户
+  │   └─ 无任何线索 → 问用户
+  │
+  ├─ 2. 确定类型 (多信号综合)
+  │   ├─ 用户指定？ → 直接用
+  │   ├─ 收集信号:
+  │   │   ├─ smart-find stats.bySpaceType 该空间最常用类型
+  │   │   ├─ 用户描述关键词: "bug"→Bug, "功能"→Story
+  │   │   └─ git 分支名: bugfix→Bug, feature→Story
+  │   ├─ 多信号一致 → 自动使用
+  │   ├─ 信号冲突/不足 → 推荐 + 让用户确认
+  │   └─ 无信号 → issue-types 列出选项 → 问用户
+  │
+  ├─ 3. type-fields 获取字段信息 + 填充
+  │   ├─ 优先级: 有则选默认值，无则不传
+  │   ├─ 必填项: 尽量填，不阻塞创建
+  │   └─ 标题: 用户提供或从描述提取
+  │
+  ├─ 4. 向用户确认 → card create
+  │   ├─ 成功 → 返回 sequence + URL
+  │   └─ 失败 → 分析错误 (类型不存在/字段不合法) → 修正重试
+  │
+  └─ 5. 返回卡片信息
+```
+
+## 关键原则
+
+1. **不确定就问**: 空间和类型是最重要的两个参数，不确定时必须确认，不要自己猜
+2. **smart-find 优先**: 先从 stats 获取用户习惯，再用其他信号验证
+3. **创建前确认**: 汇总所有信息让用户确认后再执行，避免建错卡片
+4. **始终用 --brief**: 创建后如需查看详情，用 `card get --brief`
+5. **标题很重要**: 标题是唯一不能为空的用户侧必填项，确保有意义

package/comate-engine/assets/skills/icafe-comate/references/smart-find-workflow.md

@@ -0,0 +1,127 @@
+# 智能寻卡工作流
+
+当用户需要查找卡片但没有提供完整的 space + sequence 时，使用本流程智能定位目标卡片。
+
+---
+
+## 适用场景
+
+- 用户说"帮我看看我那个 xxx 的卡片"
+- 用户说"查一下我最近的卡片"
+- 用户说"找一下登录 bug 的进度"
+- 预审/代码生成时用户没指定具体卡片
+- 修改卡片时用户只说了大概描述没给序列号
+
+## 第一步：从用户上下文提取线索
+
+分析用户的对话内容，提取以下线索（可能有多个，也可能一个都没有）：
+
+| 线索类型 | 示例 | 提取方式 |
+|---------|------|---------|
+| 明确的 space-sequence | "cloud-iCafe-22229" | 正则匹配 `{space}-{数字}` |
+| 空间名 | "cloud-iCafe 空间" | 关键词 |
+| 卡片标题关键词 | "登录 bug"、"智能预审" | 用户描述中的关键词 |
+| 卡片类型 | "那个 Task"、"Bug" | 类型关键词 |
+| 负责人 | "我的卡片"、"zhangsan 的" | 人称/用户名 |
+
+**如果提取到了明确的 space + sequence** → 直接调 `card get --brief` 验证存在性，跳到结果返回。
+
+## 第二步：确定搜索范围（空间）
+
+**2.1 用户指定了空间** → 直接使用
+
+**2.2 用户没指定空间** → 调 smart-find 获取用户活跃空间和卡片：
+
+```bash
+icafe-cli card smart-find
+```
+
+从 `stats.bySpace` 确定候选空间：
+- 只有 1 个空间 → 直接在该空间搜索
+- 有多个空间 → 结合用户描述中的关键词与卡片标题匹配，缩小到最相关的空间
+- 如果无法确定 → 列出 top 3 空间让用户选择
+
+## 第三步：在目标空间中搜索卡片
+
+按以下优先级逐级尝试，**找到就停**，不要所有方式都跑一遍：
+
+**3.1 从 smart-find 结果中匹配（如果第二步调过 smart-find）**
+
+直接在已有的 `cards` 列表中搜索，不需要额外 API 调用：
+- 过滤目标空间的卡片
+- 用用户描述中的关键词与 `title` 做模糊匹配
+- 按匹配度 + `lastModified` 时间排序
+- 如果匹配到 1 张 → 确认后返回
+- 匹配到多张 → 列出 top 5 让用户选择
+
+**3.2 用 IQL 精确搜索**
+
+如果 smart-find 结果中没匹配到，或用户提供了更具体的条件（类型、状态等），用 IQL：
+
+```bash
+# 按标题关键词搜索
+icafe-cli card query --space <space> \
+  --iql "负责人 = currentUser AND 标题 ~ <关键词>" --brief
+
+# 按类型搜索
+icafe-cli card query --space <space> \
+  --iql "负责人 = currentUser AND 类型 = Bug AND 流程状态 != 已关闭" --brief
+
+# 不限负责人（可能是别人的卡片但用户关注的）
+icafe-cli card query --space <space> \
+  --iql "标题 ~ <关键词> AND 流程状态 != 已关闭" --brief
+```
+
+> **注意**: 对 IQL 查询结果再用 `isFinishedStatus` 字段做二次过滤，排除所有已结束的卡片。
+
+**3.3 兜底：列出用户的活跃卡片**
+
+如果关键词搜索无结果，退化为列出用户在该空间的所有活跃卡片：
+
+```bash
+icafe-cli card query --space <space> \
+  --iql "负责人 = currentUser AND 流程状态 != 已关闭" \
+  --max-records 10 --brief
+```
+
+让用户从列表中选择。
+
+## 第四步：返回结果
+
+找到卡片后，返回关键信息：
+- **卡片标识**: `{space}-{sequence}` (如 `cloud-iCafe-22229`)
+- **卡片 URL**: `https://console.cloud.baidu-int.com/devops/icafe/issue/{space}-{sequence}/show`
+- **基本信息**: 标题、类型、状态、负责人
+
+## 决策流程图
+
+```
+用户要找卡片
+  │
+  ├─ 提取线索
+  │   ├─ 有明确 space+sequence？ → card get --brief 验证 → 返回
+  │   ├─ 有空间名？ → 记录，进入第三步
+  │   ├─ 有关键词/类型/人名？ → 记录，用于后续匹配
+  │   └─ 什么都没有？ → 进入第二步
+  │
+  ├─ 确定搜索空间
+  │   ├─ 已有空间 → 跳到第三步
+  │   └─ 无空间 → card smart-find
+  │       ├─ stats.bySpace 只有 1 个 → 用它
+  │       ├─ 多个 → 关键词匹配或让用户选
+  │       └─ 无结果 → 问用户
+  │
+  ├─ 搜索卡片 (找到就停)
+  │   ├─ smart-find cards 中按标题匹配 → 有结果 → 确认/选择
+  │   ├─ IQL 按关键词/类型搜索 → 有结果 → 确认/选择
+  │   └─ 兜底: 列出用户活跃卡片 → 让用户选
+  │
+  └─ 返回卡片信息
+```
+
+## 关键原则
+
+1. **能不调 API 就不调**: smart-find 有缓存（10 分钟），优先用缓存数据匹配
+2. **找到就停**: 不要把所有搜索方式都跑一遍，第一个有结果的就用
+3. **不确定就问**: 如果搜到多张卡片且无法自动判断，列出候选让用户选择，不要自己猜
+4. **始终用 --brief**: 减少上下文占用