# Aidy 与全局搜索

从页头搜索：宽屏下搜索框位于图标旁边，窄屏下点放大镜打开。在任何地方按 `Ctrl/Cmd+K` 都能聚焦或打开搜索。查询为空时，面板会列出最近的搜索、推荐视图（你未完成的待办、指派给你的工单、失败或受阻的流水线、卡住超过三天的流程，以及失败的 Argos 用例），以及每个分区的「前往」。输入关键词可搜索共享的 Work 记录、Argos 已登记的用例（`test`，打开用例源码）和运行（`argos`，打开该次运行），以及你的账号可访问的仓库、PR、流水线和制品记录；「搜索范围」可把结果限定为某一类记录。`Enter` 打开选中的结果，`Ctrl/Cmd+Enter` 把查询交给 Aidy。已安装的插件可以通过只读的 `<plugin>_search` 操作提供搜索结果。完整搜索页还为工单和待办提供「scope」和「state」筛选（例如“我的 + 未完成”）。

## 问 Aidy

点击页头的 Acahti 标志会打开侧边栏，它是页面旁边一个可调整宽度的面板。侧边栏有两个标签页：「Aidy」和「消息」（你和其他人的聊天）。页头徽标统计未读聊天、提及以及你还没看过的 Aidy 回复。把页头切换到「智能体」，侧边栏就成为主界面并展开 Aidy；切回「仪表盘」则返回原页面。浏览器会记住侧边栏是否打开、宽度、模式、当前标签页以及每个标签页上的会话，刷新后一切照旧。

![合成示例工作区中智能体模式下的 Aidy](/docs/images/aidy.png)

Aidy 的会话保存在服务器上。「新对话」开始一个新会话；「历史」按时间倒序列出之前的会话，可以重新打开、重命名或删除。CLI 和 MCP 看到的是同一批会话。

提一个问题或下一条指令，例如：

- Which of my tickets are still open?
- 创建一个 Star Map 新项目
- 给 TurboMesh 建一个 todo：写 1.3 发布说明
- 把 #311 指给 lipeiyang
- Open the TurboMesh iterations.

Aidy 是运行在所配置模型上的 Agent。它能看到**你**可以通过 MCP 调用的操作（相同的目录、权限和插件授权），并自行决定是搜索、读取记录还是执行操作：

- **读取**（搜索、列表、记录、流水线日志……）立即执行；回复中每次查询都显示为一行可折叠的活动记录。
- **写入**要等你确认。Aidy 会显示一张卡片，列出操作及其确切参数，在你点「确认」之前不会执行任何操作；「取消」则放弃该操作。可能覆盖或删除已有数据的写入（更新、删除、归档、合并、权限变更）会标为「破坏性操作」。不做决定而直接提新问题，会取消正在等待的写入。
- **打开页面**：当你要求打开或查看某个内容时，Aidy 会在左侧打开它（从智能体模式回到仪表盘），支持工单、待办、项目、知识库、仓库、流水线、制品、追踪和 Argos 等产品路由。

确认后的写入以你的身份执行，因此会在与 MCP 中完全相同的地方失败。Aidy 不会提供修改它自身设置、设置密钥值、创建成员（会返回一次性密码）或从 URL 发布制品的操作；这些请使用 MCP 或 CLI。每次回复最多进行八轮模型调用和十六次操作，长结果只读取开头部分。回答会链接它所依据的记录，引用的来源列在回复下方。工具结果一律当作数据，绝不当作指令。

## 用 Aidy 做规划

规划页面会把问题交给 Aidy，Aidy 读取与你看到的相同的数字（`planning_brief`），并提出修改建议供你确认：

- 「让 Aidy 写进展」（项目）和「问 Aidy」（迭代）：一份状态更新，包含健康度（正常、有风险或偏离）及其依据、进度、带链接的风险和范围变更、负载与容量对比，以及下一步计划。
- 发布或取消迭代时的「让 Aidy 提议」：一次 `iteration_close`，带上每个未完成的待办，保留在本迭代的待办附上理由。
- 「提交交付」中的「让 Aidy 起草」：先调用 `delivery_draft`，再生成按功能和修复分组的变更日志，在任何 `delivery_submit` 之前展示给你。
- 「填写当天工时」中的「让 Aidy 帮我填」：先调用 `time_entry_suggest`，再为每条记录调用一次 `time_entry_save` 并附上依据。

也可以用自己的话问：“估一下 1.17 的待办”、“1.17 开始以来范围有哪些变化”、“我哪些待办已逾期”。

## 配置模型后端

组织管理员打开「管理 → Aidy 设置」。默认模型为 `qwen-flash`，默认端点是 DashScope 的 OpenAI 兼容 API。设置 API 端点、模型和 API key，并启用模型回答。端点必须使用 HTTPS。key 使用实例持久的会话密钥加密存储，设置 API 永远不会返回它。key 字段保持不变则沿用现有 key。运维人员也可以通过 `ACAHTI_AIDY_API_KEY` 提供。

Aidy 以流式方式调用端点的 chat completions，并使用 function calling（`tools`），因此模型必须支持工具调用；`qwen-flash` 支持。未配置模型时，Aidy 会把共享搜索针对该问题的命中结果作为 `sources` 返回，并带上 `configured: false`。全局搜索独立工作，不受影响。

## Agent 访问

CLI、MCP 和侧边栏访问的是同一批会话和同一个 Agent。

```bash
acahti aidy ask --question "创建一个 Star Map 新项目"        # starts a conversation
acahti aidy ask --question "也加上 lipeiyang" --conversation 12
acahti aidy confirm 12 --call call_ab12            # approve the pending write
acahti aidy confirm 12 --call call_ab12 --cancel   # or cancel it
acahti aidy list
acahti aidy view 12
acahti aidy rename 12 --title "Star Map"
acahti aidy delete 12
acahti aidy settings
acahti mcp call aidy_ask '{"question":"Which of my tickets are still open?"}'
```

`aidy_ask` 返回 `conversation`、`answer`、`tools`（已执行的操作）、`pending`（等待 `aidy_confirm` 的写入，以其 `id` 作为 `call_id`）、`navigate`、引用的 `sources`、`model` 和 `configured`。`aidy_confirm` 执行或取消待处理的写入，并以相同结构返回回复的剩余部分。`aidy_conversation_list`、`aidy_conversation_get`、`aidy_conversation_update` 和 `aidy_conversation_delete` 用于管理历史。自己持有操作目录的 Agent 可以跳过 Aidy，直接调用这些操作。

`aidy_configure` / `acahti aidy configure --body-file -` 需要组织管理员权限。密钥类参数通过 stdin 传入，不要写在命令行或共享文档里。