ccc

ccc - 语义代码搜索与索引

ccc 是 CocoIndex Code 的 CLI，可对当前代码库进行语义搜索并管理索引。

所有权

Agent 负责当前项目中 ccc 的整个生命周期——初始化、索引和搜索。不要让用户执行这些步骤；请自动处理。

• 初始化：如果 ccc search 或 ccc index 因初始化错误而失败（例如“Not in an initialized project directory”），请从项目根目录运行 ccc init，然后运行 ccc index 构建索引，再重试原始命令。
  • 例外：如果 ccc index 因目录中包含 ccc 的用户设置目录（通常是你的主目录）而拒绝执行，请勿在该目录运行 ccc init。请改为在项目内运行 ccc，或询问用户要使用哪个项目。
  • 例外：如果 ccc 的提示说明该目录就是正在使用的项目（其下的仓库没有自己的项目），请告知用户。不要自行在该目录运行 ccc reset：是否应将其保留为项目由用户决定。
• 索引新鲜度：当索引可能已过期时，运行 ccc index（或 ccc search --refresh）以保持索引最新，例如在会话开始时，或进行重大代码更改后（新增文件、重构、重命名模块）。如果连续搜索之间没有更改代码，则无需重新建立索引。
• 安装：如果找不到 ccc 本身（提示找不到命令），请参阅 management.md 中的安装说明，并告知用户。

搜索代码库

执行语义搜索：

ccc search <query terms>

查询应描述要查找的概念、功能或行为，而不是精确的代码语法。例如：

ccc search database connection pooling
ccc search user authentication flow
ccc search error handling retry logic

筛选结果

• 按语言筛选（--lang，可重复）：将结果限制为指定语言。

  ccc search --lang python --lang markdown database schema
  

• 按路径筛选（--path）：将结果限制为相对于项目根目录的 glob 模式。如果省略，则默认为当前工作目录（仅返回该子目录下的结果）。

  ccc search --path 'src/api/*' request validation
  

分页

结果默认显示第一页。要获取更多结果：

ccc search --offset 5 --limit 5 database schema

如果返回的结果看起来都相关，请使用 --offset 获取下一页——第一页之后可能还有更多有用的匹配项。

使用搜索结果

搜索结果包含文件路径和行范围。要进一步查看结果：

• 使用编辑器内置的文件读取功能（例如 Read 工具）加载匹配的文件，并阅读返回范围附近的行以获取完整上下文。
• 在没有文件读取工具的终端中，使用 sed -n '<start>,<end>p' <file> 提取指定行范围。

设置

如需查看或编辑嵌入模型配置、包含／排除模式或语言覆盖项，请参阅 settings.md。

管理与故障排除

有关安装、初始化、守护进程管理、故障排除和清理命令，请参阅 management.md。