Osori（오소리）

面向 AI 代理的本地项目注册中心与上下文加载器。

前置条件

• macOS：mdfind（Spotlight，系统内置）、python3、git、gh CLI
• Linux：mdfind 不可用 → 自动回退使用 find；需安装 python3、git、gh CLI。
• 完整集成（可选）：已安装 entire CLI（用于 /entire-* 命令）

依赖项

• python3 — 必需。用于 JSON 处理。
• git — 项目检测与状态检查。
• entire — 可选。仅在执行 /entire-status、/entire-enable、/entire-rewind-list 时需要。

Telegram Bot 命令（v1.6.1 版本更新）

Osori 现已支持 Telegram 斜杠命令，实现快速项目管理：

/list [root] — 显示已注册项目（可选 root 过滤）
/status [root] — 检查项目状态（可选 root 过滤）
/find  [root|--root ] — 按名称查找项目（可选 root 范围）
/switch  [root|--root ] [--index ] — 切换至项目并加载上下文（支持多匹配结果选择）
/fingerprints [name] [--root ] — 显示仓库远程地址 + 最近一次提交 + 开放 PR/Issue 数量
/doctor [--fix] [--dry-run] [--yes] [--json] — 注册中心健康检查（预览优先、风险受控修复）
/list-roots — 列出所有 roots、标签、路径及项目数量
/root-add  [label] — 添加 root（或更新其标签）
/root-path-add   — 向 root 添加发现路径
/root-path-remove   — 从 root 中移除发现路径
/root-set-label   — 更新 root 标签
/root-remove  [--reassign ] [--force] — 安全移除 root
/alias-add   — 为项目添加别名
/alias-remove  — 移除别名
/favorites — 显示收藏项目
/favorite-add  — 将项目标记为收藏
/favorite-remove  — 取消项目收藏
/entire-status  [root|--root ] — 显示项目中的 Entire 状态
/entire-enable  [root|--root ] [--agent ] [--strategy ] — 在项目中启用 Entire
/entire-rewind-list  [root|--root ] — 列出项目中的 rewind 点
/add  — 将项目加入注册中心
/remove  — 从注册中心移除项目
/scan  [root] — 扫描目录下的 Git 项目（可选指定 root）
/help — 显示命令帮助

配置方法

将以下内容添加至您的 OpenClaw 代理的 TOOLS.md 或 Telegram Bot 配置中：

# 在 Telegram Bot 命令设置中（BotFather）
list - 显示所有项目（或按 root 过滤）
status - 检查项目状态（或按 root 过滤）
find - 按名称查找项目
switch - 切换至项目
fingerprints - 显示仓库/提交/PR/Issue 指纹信息
doctor - 健康检查（预览优先、风险受控修复）
list-roots - 显示 roots 和发现路径
root-add - 添加 root
root-path-add - 向 root 添加路径
root-path-remove - 从 root 移除路径
root-set-label - 重命名 root 标签
root-remove - 安全移除 root（支持 reassign/force 选项）
alias-add - 为项目添加别名
alias-remove - 移除别名
favorites - 显示收藏项目
favorite-add - 将项目标记为收藏
favorite-remove - 取消项目收藏
entire-status - 显示项目中的 Entire 状态
entire-enable - 为项目启用 Entire
entire-rewind-list - 列出项目中的 rewind 点
add - 将项目加入注册中心
remove - 从注册中心移除项目
scan - 扫描目录（可选指定 root）
help - 显示帮助

使用示例

/list work
/status personal
/find agent-avengers work
/switch Tesella --root personal
/switch Tesella --root personal --index 1
/fingerprints Tesella --root personal
/doctor --fix
/list-roots
/root-add work Work
/root-path-add work /path/to/workspace
/root-remove work --reassign default
/alias-add rh RunnersHeart
/favorite-add RunnersHeart
/favorites
/entire-status osori
/entire-enable osori --agent claude-code --strategy manual-commit
/add /Volumes/disk/MyProject
/scan /path/to/workspace work

注册中心

${OSORI_REGISTRY:-$HOME/.openclaw/osori.json}

可通过 OSORI_REGISTRY 环境变量覆盖默认路径。

版本控制与迁移（v1.6.1）

• 当前 schema：osori.registry
• 当前版本：2
• 每次加载时，Osori 自动迁移旧版注册中心格式：
  • 旧版数组格式（[]）→ 带版本号的对象格式
  • 无 schema/version 字段的对象 → 规范化的带版本号对象
• 规范化注册中心字段：
  • 顶层 roots[]
  • 顶层 aliases{}（别名 → 项目名称映射）
  • 每个 projects[] 条目包含 favorite: bool 字段
• 迁移安全性保障：
  • 自动创建备份文件：osori.json.bak-
  • 损坏的 JSON 将保留为：osori.json.broken-
  • 写入路径采用原子替换 + 回滚备用机制

项目查找（路径未知时）

当项目路径未知时，按以下顺序搜索：

1. 注册中心查找 — 在 osori.json 中对名称进行模糊匹配
2. mdfind（仅 macOS）— mdfind "kMDItemFSName == ''" | head -5
3. find 回退 — 搜索优先级：
   1. 注册中心中 roots[].paths（若指定了 root，则优先搜索该 root）
   2. OSORI_SEARCH_PATHS 中定义的路径
      命令形式：find -maxdepth 4 -type d -name '' 2>/dev/null
4. 向用户询问 — 若所有方法均失败，则直接请求用户提供项目路径。
5. 提供将已找到项目注册进注册中心的选项。

命令说明

List

显示所有已注册项目。Telegram 命令支持可选的 root 过滤：

/list [root]

（示例：/list work）

Switch

支持可选的 root 范围和显式候选项目选择：

/switch  [root|--root ] [--index ]

执行流程：

1. 搜索注册中心（模糊匹配；若提供了 root，则限定范围）
2. 若存在多个匹配项：
   • 展示候选列表（含名称/root/路径/最近一次提交/是否脏/得分）
   • 使用 --index 显式选取
   • 未指定 index ⇒ 自动选取最高分项
3. 若未找到 → 执行上方“项目查找”流程，并建议添加路径
4. 加载上下文：
   • git status --short
   • git branch --show-current
   • git log --oneline -5
   • gh issue list -R --limit 5（仅当设置了 repo 时）
5. 输出摘要信息

自动评分策略：

• +50 root 精确匹配（若提供了 root 范围）
• +30 名称精确匹配
• +20 名称前缀匹配
• +10 最近一次提交时效性
• -10 缺失路径
• -5 缺失 repo
• 并列时断点规则：按最近一次提交时间排序，再按名称排序

Fingerprints

显示项目的单次指纹视图：

• 仓库远程 URL
• 最近一次提交哈希值与日期
• 开放 PR 数量
• 开放 Issue 数量

bash {baseDir}/scripts/project-fingerprints.sh [project-name]
bash {baseDir}/scripts/project-fingerprints.sh --root  [project-name]

GitHub 开放计数缓存（PR / Issue）：

• 默认缓存文件：$HOME/.openclaw/osori-cache.json
• 默认 TTL：600 秒
• 环境变量覆盖项：
  • OSORI_CACHE_FILE
  • OSORI_CACHE_TTL

Add

bash {baseDir}/scripts/add-project.sh  [--tag ] [--name ]

自动识别：Git 远程地址、编程语言、描述信息。

Scan

bash {baseDir}/scripts/scan-projects.sh  [--depth 3]
OSORI_ROOT_KEY=work bash {baseDir}/scripts/scan-projects.sh  [--depth 3]

批量扫描目录下的 Git 仓库，并将其加入注册中心。

Telegram 命令也支持可选的 root key：

/scan  [root]

Remove

按名称从 osori.json 中删除对应条目。

Status

对一个或全部项目运行 git status + gh issue list。

Telegram 支持 root 过滤：

/status [root]

Doctor

注册中心健康检查，采用预览优先管道与风险受控修复机制。

默认行为（不带任何标志）：仅分析 + 预览方案，不执行任何变更。

/doctor                     # 仅预览（默认行为）
/doctor --fix               # 预览 + 应用（高风险操作被阻止）
/doctor --fix --yes         # 预览 + 全量应用（含高风险操作）
/doctor --dry-run           # 显式仅预览（永不执行变更）
/doctor --json              # 输出机器可读 JSON 格式

风险等级说明：

• 🟢 低风险 — schema 规范化、迁移、缺失字段补全
• 🟡 中风险 — 去重、root 引用修复
• 🔴 高风险 — 从损坏状态重新初始化注册中心

Shell 等效命令：

bash {baseDir}/scripts/doctor.sh [--fix] [--dry-run] [--yes] [--json]

另请参阅：Doctor Safe Fix Guide

Root 管理

/list-roots
/root-add  [label]
/root-path-add  
/root-path-remove  
/root-set-label  
/root-remove  [--reassign ] [--force]

Shell 等效命令：

bash {baseDir}/scripts/root-manager.sh list
bash {baseDir}/scripts/root-manager.sh add  [label]
bash {baseDir}/scripts/root-manager.sh path-add  
bash {baseDir}/scripts/root-manager.sh path-remove  
bash {baseDir}/scripts/root-manager.sh set-label  
bash {baseDir}/scripts/root-manager.sh remove  [--reassign ] [--force]

remove 安全规则：

• default root 不可被移除
• 若 root 中存在项目：
  • 使用 --reassign 将项目迁移后再移除
  • 或使用 --force 将项目迁移至 default 后再移除

别名与收藏

/alias-add  
/alias-remove 
/favorites
/favorite-add 
/favorite-remove 

Shell 等效命令：

bash {baseDir}/scripts/alias-favorite-manager.sh alias-add  
bash {baseDir}/scripts/alias-favorite-manager.sh alias-remove 
bash {baseDir}/scripts/alias-favorite-manager.sh aliases
bash {baseDir}/scripts/alias-favorite-manager.sh favorite-add 
bash {baseDir}/scripts/alias-favorite-manager.sh favorite-remove 
bash {baseDir}/scripts/alias-favorite-manager.sh favorites

别名不区分大小写，且会被 /find、/switch 及 project-fingerprints.sh 的名称查询所解析。

Entire 集成

在已注册项目的上下文中运行 Entire CLI 命令：

/entire-status  [root|--root ]
/entire-enable  [root|--root ] [--agent ] [--strategy ]
/entire-rewind-list  [root|--root ]

Shell 等效命令：

bash {baseDir}/scripts/entire-manager.sh status  [root|--root ]
bash {baseDir}/scripts/entire-manager.sh enable  [root|--root ] [entire enable flags...]
bash {baseDir}/scripts/entire-manager.sh rewind-list  [root|--root ]

默认值：

• entire enable 若未指定参数，默认使用 --agent claude-code --strategy manual-commit。
• /entire-rewind-list 使用非破坏性 JSON 列表方式（即 entire rewind --list）。

Schema

{
  "schema": "osori.registry",
  "version": 2,
  "updatedAt": "2026-02-16T00:00:00Z",
  "roots": [
    {
      "key": "default",
      "label": "Default",
      "paths": []
    }
  ],
  "aliases": {
    "rh": "RunnersHeart"
  },
  "projects": [
    {
      "name": "string",
      "path": "/absolute/path",
      "repo": "owner/repo",
      "lang": "swift|typescript|python|rust|go|ruby|unknown",
      "tags": ["personal", "ios"],
      "description": "Short description",
      "addedAt": "YYYY-MM-DD",
      "root": "default",
      "favorite": false
    }
  ]
}

自动触发规则

• “work on X” / “X 프로젝트 작업하자” → 执行 switch X
• “find project X” / “X 찾아줘” / “X 경로” → 执行注册中心查找或发现流程
• “list projects” / “프로젝트 목록” → 执行 list
• “add project” / “프로젝트 추가” → 执行 add
• “project status” / “프로젝트 상태” → 执行 status all