lov-ataru-search

name	lov-ataru-search
description	从本机 Ataru 记忆索引里召回过去的 AI 会话上下文，返回可定位的命中与原文片段。 Use when asked what was discussed, decided, or fixed in an earlier session.
license	MIT
metadata	{"author":"lovstudio","version":"0.2.0","card_standard":"lovstudio/skill-card/v1","tags":["ataru","search","recall","local-first"],"compatibility":"Portable Agent Skills format. Requires Python 3.8+ and a locally installed Ataru binary at 0.41.3 or newer.","dependencies":[]}

lov-ataru-search — 从本地记忆里召回上下文

在本机已有的 AI 会话历史里找出与当前问题相关的过去记录，交回两样能直接用的 东西：带稳定标识（Project / Session / Message）的排序命中，以及围绕某个命中的一段 原文。索引的构建与修复属于 lov-ataru-indexing。

Triggers

Activate when

• “我上次是怎么解决这个报错的？”
• “找出讨论过会话恢复方案的那次记录。”
• Help me recall what was decided about this module in an earlier session.

Do not activate when

• 用户要的是「把索引重建一下」「索引是不是坏了」 —— 交给 lov-ataru-indexing。
• 用户要在当前代码库里找某个符号或文件 —— 用普通的 grep 与文件搜索，那是代码检索 而不是会话记忆检索。

User Profile (cross-session)

skill.yaml 声明 user-profile/v1。每次运行开始时读取共享的 user、brand、 workspace、preferences 以及本 Skill 的 skills.lov-ataru-search 命名空间。

值得长期保存的记录有两项：records.ataru_bin（本机可用的 Ataru 可执行文件路径）与 records.default_level（用户偏好的检索粒度）。用户直接说出这类值时，用 scripts/profile_store.py record 写回并报告保存路径。检索词、项目 ID 这类一次性 输入不写入 Profile。完整契约见 references/user-profile.md。

Skill Group Composition

见 references/skill-composition.md。本源码是 独立 Single Skill，与 lov-ataru-indexing 之间只有制品级交接（索引状态）。

Workflow (MANDATORY)

You MUST follow these steps in order.

Step 0: Resolve the binary, then confirm the index

export SKILL_DIR="$HOME/.claude/skills/lov-ataru-search"
python3 "$SKILL_DIR/scripts/ataru_recall.py" index-status

解析顺序是 --bin → ATARU_BIN → PATH → 已安装 App bundle → 从当前目录向上查找的 本地 dev build，每个候选先跑一次 --version。低于 0.41.3 的旧版不认识 index 子命令， 会把它当成桌面启动参数打开一个窗口并永不返回。

search 自己会先确认索引。索引未就绪时它以 ATARU_INDEX_NOT_READY 或 ATARU_INDEX_BUILDING 失败并指向 lov-ataru-indexing，不会返回零结果—— 「没找到」和「索引没建好」必须是两种可区分的回答。本 Skill 不替用户构建索引。

Step 1: Choose the level before querying

level	一条命中代表	什么时候用
turn	单条消息	默认。要精确定位某句话、某个报错、某个决定
run	一轮用户请求到回答	想看一个来回的完整语境
session	整个会话	想找「哪次会话在讨论这件事」
project	一个项目	想知道这个话题主要发生在哪个项目里

python3 "$SKILL_DIR/scripts/ataru_recall.py" search "会话恢复方案" --level turn --limit 10

限定项目时用等号形式，因为项目 ID 本身以短横线开头：

python3 "$SKILL_DIR/scripts/ataru_recall.py" search "索引没有更新" \
  --level session --project-id=-Users-me-projects-app

命中里的 projectId / sessionId / messageId / lineNumber 是稳定标识，可以直接 喂给下一步。snippet 默认截断到 600 字符，需要完整 CLI 响应时加 --full。

命令行检索只走关键词模式：mode 与 requestedMode 都会是 keyword， semanticAvailable 通常为 false。不要向用户承诺命令行能拿到语义或 hybrid 排序， 也不要因为关键词没命中就断言「历史里没有这件事」——换同义词、换 level 再试。

在万级会话的真实语料上，一次 turn 级检索是数十秒量级。不要为了「快速失败」压低 --timeout。

Step 2: Read the original transcript around a hit

排序命中只够定位，不够下判断。拿到候选后，围绕它读一段原文：

python3 "$SKILL_DIR/scripts/ataru_recall.py" read \
  --project-id=-Users-me-projects-app \
  --session-id=<session uuid> \
  --around=<message uuid or line number> \
  --window 6

--window 是每侧保留的消息数，--message-chars 控制单条正文截断（默认 2000）。 不传 --around 时返回会话末尾 --window 条。给出的 --around 在该会话里找不到时， 脚本报 ATARU_MESSAGE_NOT_FOUND 而不是静默返回别的位置。

Step 3: Answer with citations, not with impressions

回答里必须带得回原处的东西：会话标题、时间戳，以及必要时的 sessionId。截断过的 正文要说明是截断的。检索没命中就说没命中，并说明用了哪些词和哪个 level —— 不要用当前上下文的推测去填补历史空白。

Dependencies

• Python 3.8+（仅标准库）
• 本机安装的 Ataru 0.41.3 或更新版本，且索引已就绪

通用反馈闭环

用户在 Skill 驱动任务中提出修改意见时，继续当前产物前必须执行：

1. 先判断意见是 task-specific（仅本次）还是 reusable（可跨任务复用）。
2. task-specific 只修改当前任务，不改 Skill。
3. reusable 先确定作用域：领域规则先更新对应 canonical Skill；适用于所有 Skill 的规则先更新共享规范。
4. 完成规则更新、版本、lint 与分发核验后，再把修改应用到当前任务。
5. reusable 修改会使此前的“确认”“继续”“发吧”失效；完成当前产物修改和回读后必须停下，等待用户下一步指示，不自动进入发布、提交或其他外部写入。