cangjie-docs-search-guide

目的

当所需知识在基础 skills 中缺失或不明确时，通过读取本地索引文件定位目标 API 文档，随后读取完整文档以获取官方标准实现和上下文作为兜底，严禁凭空想象仓颉代码。

核心原则：所有实现与修改必须以官方文档为最终依据，严禁凭空猜测仓颉语法或 API。

检索流程

必须严格遵守以下步骤，缺一不可！

步骤 0：确认检索关键词

根据基础 skills 中缺失或不明确的知识点生成 “核心技术关键词”

步骤 1：锁定目标索引文件

所有本地官方文档索引文件位于：

.opencode/skills/cangjie-docs-search-guide/index/

根据关键词对比以下分类大纲，确定知识点所属的索引文件：

分类大纲目录

1. 语言基础特性与语法 → 目标索引: .opencode/skills/cangjie-docs-search-guide/index/syntax.md

   覆盖内容包括：

   • 基本概念（标识符、程序结构、表达式、函数）
   • 基础数据类型（基本操作符、整数类型、浮点类型、布尔类型、字符类型、字符串类型、元组类型、数组类型、区间类型、Unit 类型、Nothing 类型）
   • 函数（定义函数、调用函数、函数类型、嵌套函数、Lambda 表达式、闭包、函数调用语法糖、函数重载、操作符重载、const 函数和常量求值）
   • 结构类型（定义 struct 类型、创建 struct 实例、mut 函数）
   • 枚举类型和模式匹配（枚举类型、Option 类型、模式概述、模式的 Refutability、match 表达式、其他使用模式的地方）
   • 类和接口（类、接口、属性、子类型关系、类型转换）
   • 泛型（泛型概述、泛型函数、泛型接口、泛型类、泛型结构体、泛型枚举、泛型类型的子类型关系、类型别名、泛型约束）
   • 扩展（扩展概述、直接扩展、接口扩展、访问规则）
   • Collection 类型（基础 Collection 类型概述、ArrayList、HashSet、HashMap、Iterable 和 Collections）
   • 包（包的概述、包的声明、顶层声明的可见性、包的导入、程序入口）
   • 异常处理（定义异常、throw 和处理异常、常见运行时异常、使用 Option）
   • 并发编程（并发概述、创建线程、访问线程、终止线程、同步机制、线程睡眠指定时长 sleep）
   • 基础 I/O 操作（I/O 流概述、I/O 节点流、I/O 处理流）
   • 网络编程（网络编程概述、Socket 编程、HTTP 编程、WebSocket 编程）
   • 宏（宏的简介、Tokens 相关类型和 quote 表达式、语法节点、宏的实现、编译、报错与调试、宏包定义和导入、内置编译标记、实用案例）
   • 反射和注解（动态特性、注解）
   • 跨语言互操作（仓颉-C 互操作）
   • 编译和构建（cjc 使用、cjpm 介绍、条件编译）
   • 部署和运行（部署仓颉运行时、运行仓颉可执行程序）
   • 附录（cjc 编译选项、Linux 版本工具链的支持与安装、runtime 环境变量使用手册、关键字、操作符、操作符函数、TokenKind 类型、仓颉包兼容性检查）

2. 标准库 (stdlib) → 目标索引: .opencode/skills/cangjie-docs-search-guide/index/stdlib.md

   覆盖的主要模块包括：

   • std.core（函数、类型别名、内置类型、接口、类、枚举、结构体、异常类）
   • std.argopt（函数、类、枚举、结构体、异常类）
   • std.ast（函数、接口、类、枚举、结构体、异常类）
   • std.binary（接口）
   • std.collection（函数、接口、类、异常类）
   • std.collection.concurrent（类型别名、接口、类）
   • std.console（类）
   • std.convert（接口）
   • std.crypto.cipher（接口）
   • std.crypto.digest（函数、接口）
   • std.database.sql（接口、类、枚举、异常类）
   • std.deriving（宏）
   • std.env（函数、类、异常类）
   • std.fs（函数、类、枚举、结构体、异常类）
   • std.io（函数、接口、类、枚举、异常类）
   • std.math（接口、函数、枚举）
   • std.math.numeric（函数、枚举、结构体）
   • std.net（接口、类、枚举、结构体、异常类）
   • std.objectpool（类）
   • std.overflow（接口、异常类）
   • std.posix（常量&变量、函数）
   • std.process（函数、类、枚举、异常类）
   • std.random（类）
   • std.ref（类、枚举）
   • std.reflect（函数、类型别名、类、枚举、异常类）
   • std.regex（类、枚举、结构体、异常类）
   • std.runtime（函数、结构体）
   • std.sort（函数、接口）
   • std.sync（常量&变量、接口、类、枚举、结构体、异常类）
   • std.time（类、枚举、结构体、异常类）
   • std.unicode（接口、枚举）
   • std.unittest 系列（包括 mock、mockmacro、testmacro、common、diff、prop_test 等）

3. 扩展库 (stdx) → 目标索引: .opencode/skills/cangjie-docs-search-guide/index/stdx.md

   覆盖的主要模块包括：

   • stdx.aspectCJ（类，示例教程：AOP 开发示例）
   • stdx.compress.zlib（类、枚举、异常类，示例教程：Deflate/Gzip 数据的压缩和解压）
   • stdx.crypto.crypto（类、结构体、异常类，示例教程：SecureRandom/SM4 使用）
   • stdx.crypto.digest（类、结构体、异常类，示例教程：digest 使用）
   • stdx.crypto.keys（类、枚举、结构体，示例教程：keys 使用）
   • stdx.crypto.x509（类型别名、接口、类、枚举、结构体、异常类，示例教程：x509 使用）
   • stdx.encoding.base64（函数，示例教程：Byte 数组和 Base64 互转）
   • stdx.encoding.hex（函数，示例教程：Byte 数组和 Hex 互转）
   • stdx.encoding.json（接口、类、枚举、异常类，示例教程：JsonArray 使用示例 / JsonValue 与 String 互转 / JsonValue 与 DataModel 的转换）
   • stdx.encoding.json.stream（接口、类、枚举、结构体，示例教程：使用 Json Stream 进行反序列化/序列化、WriteConfig 使用示例）
   • stdx.encoding.url（类、异常类，示例教程：Form 构造与 URL 解析）
   • stdx.fuzz.fuzz（常量&变量、类、异常类，示例教程：fuzz 使用与覆盖率处理等）
   • stdx.log / stdx.logger（类型别名、函数、接口、类、结构体、异常类，示例教程：日志打印示例）
   • stdx.net.http（函数、接口、类、枚举、结构体、异常类，示例教程：client/cookie/log/server/webSocket/h1_gzip 等）
   • stdx.net.tls（类、枚举、结构体、异常类，示例教程：客户端/服务端示例、证书热更新等）
   • stdx.serialization.serialization（函数、接口、类、异常类，示例教程：class/HashSet/HashMap 序列化）
   • stdx.unittest.data（函数、类）

4. 编译构建与命令行工具 → 目标索引: .opencode/skills/cangjie-docs-search-guide/index/tools.md

   覆盖的内容包括：

   • 项目管理工具
   • 调试工具
   • 格式化工具
   • 静态检查工具
   • 覆盖率统计工具
   • 语言服务器工具
   • CHIR 反序列化工具
   • 异常堆栈信息还原工具
   • 性能分析工具

在任何情况下，你都不得臆测文档路径，必须按照下面的分步流程通过索引文件查找到真实文档路径。

步骤 2：读取索引文件提取目标路径

锁定目标索引文件后，警告：严禁臆测 API 文档路径！ 必须严格执行以下操作：

1. 明确调用自带的 Read 工具，将步骤 1 锁定的索引文件（如 .opencode/skills/cangjie-docs-search-guide/index/stdx.md）全文读入。
2. 在读入的索引文件内容中，寻找你在步骤 1 确定的“知识点/模块”（例如找 stdx.net.http）。
3. 提取该模块下对应文档的真实相对路径（即 Markdown 链接括号 () 内的路径片段）。

操作要求：

1. 必须使用 Read 工具 全文读取被选中的索引文件；
2. 在索引文件中，找到与你的关键词最匹配的“知识点/模块”条目；
3. 从该条目的 Markdown 链接中提取出真实的 相对路径片段（即 (... ) 括号中的路径）。

步骤 3：读取目标文档

获取相对路径后，执行以下操作：

1. 防 API 阻断强制约束：为了防止 API Payload 过大导致 400 报错，每次调用 Read 工具最多只允许读取 1 到 2 个最核心的文档！严禁一次性读取 3 个及以上文件。尽量不要读取名称包含 _classes.md、_funcs.md 或 _interfaces.md 的巨型 API 字典文件！ 你尽量寻找并读取名称包含 _samples.md（示例代码）或 _overview.md （概览与基本用法）的文件。

2. 拼接绝对读取路径：根据索引文件来源将刚刚提取到的相对路径拼接为实际文件路径：：

• syntax.md 索引 → 拼接到：
  • .opencode/skills/cangjie-docs-search-guide/syntax/{相对路径}
• stdlib.md 索引 → 拼接到：
  • .opencode/skills/cangjie-docs-search-guide/stdlib/{相对路径}
• stdx.md 索引 → 拼接到：
  • .opencode/skills/cangjie-docs-search-guide/stdx/{相对路径}
• tools.md 索引 → 拼接到：
  • .opencode/skills/cangjie-docs-search-guide/tools/{相对路径}

3. 明确调用自带的 Read 工具，将拼接后的目标文档全文读入上下文。

4. 读取完目标文档后，你应当：

• 提取其中的 import 声明；
• 标出关键 API 的完整签名（函数名、参数、返回值）；
• 关注官方给出的示例代码及注意事项；
• 严格以文档为准设计/修改仓颉代码。

步骤 4：基于官方文档执行开发与排错

完成文档阅读后，你需要：

• 将当前工程中的代码实现与官方示例对照检查：
  • 包导入是否正确。
  • 类型/泛型参数是否匹配。
  • 错误处理是否符合推荐模式（异常 vs Option）。
  • 网络/IO/并发等敏感模块是否按照推荐模式使用。
• 引用 API 时，不得擅自更改签名或臆测重载版本。

步骤 5：自我检查与回溯

每次检索后应回答以下问题：

1. 当前修改/实现的代码，是否可以在官方文档中找到直接或高度相似的示例？
2. 是否存在"凭感觉写的语法"或"凭记忆写的 API 名称"？如有，应重新确认。
3. 是否遗漏了文档中强调的"注意事项/警告/边界条件处理"？

上述问题均得到肯定回答后，方可认为本次检索任务完成。