企业官网建设流程全解析

• 开发工具
• CLI
• 代码质量

cangjie_tools是仓颉（Cangjie）编程语言的官方命令行工具链仓库，聚合了项目管理、代码格式化、静态检查、覆盖率、兼容性检查、多语言桥接、语言服务、性能分析与堆栈还原等九大工具。本文基于仓库根目录的 README_zh.md 展开，结合各工具子目录下的真实源码、配置与测试，帮助读者建立对整个工具链的全局认知，并掌握其构建依赖、目录规范与第三方组件集成方式，为后续单独构建或使用某个工具打下基础。

一、整体架构：DevEco Studio 与命令行工具链的分层关系

从仓库的 README_zh.md 与上述架构图可以看出，工具链位于 DevEco Studio 之下，形成两层结构：

• 上层（IDE）：DevEco Studio 作为客户端入口，开发者可以直接在 IDE 中使用这些能力，也可以在纯命令行环境独立调用。
• 中层（工具链）：即本仓库提供的九个工具，彼此之间以“仓颉扩展库”为共享依赖，并共同依赖仓颉编译器完成词法/语法分析等前端能力。
• 下层（依赖项）：仓颉编译器、仓颉扩展库，以及 Flatbuffers、JSON for Modern C++、SQLite 三个第三方开源组件（详见后文“第三方开源软件”一节）。

cangjie_tools当前支持在Windows x86-64、Linux x86-64/AArch64、Mac x86/arm64平台上运行，鸿蒙平台支持正在开发中（见 README_zh.md 平台说明段落）。

二、工具链组成：九大工具的功能定位与源码印证

README_zh.md 列出了工具链的完整清单。下表在继承该清单的基础上，结合各工具目录中的实际代码与配置补充了实现层面的佐证。

从源码结构看，工具链存在明显的“两种实现路线”：命令行编排类工具（cjpm、cjcov、hle、cjtrace-recover等）使用仓颉语言自身实现，可复用自己的编译器与标准库；需要深度对接编译器前端或高性能处理类工具（lsp、cjfmt、cjlint、cjcompat、cjprof）则使用 C++ 实现，直接链接仓颉编译器前端产物。

cjpm：项目管理与统一编译入口

cjpm是仓颉项目模块系统的管理工具。其开发者指南 cjpm/doc/developer_guide_zh.md 说明它提供项目创建、构建、运行、单元测试等能力，架构上分为命令行参数处理、配置管理（cjpm.toml）、依赖管理、项目构建、项目测试、编译器对接六大模块。

从源码结构可以印证这一划分（见 cjpm/doc/developer_guide_zh.md 目录说明）：

cjpm/src |-- command # 命令功能代码（init/build/run/test/install...） |-- config # 配置内容代码（cjpm.toml 解析） |-- implement # 内部接口实现代码 |-- toml # toml 文件读写功能代码 `-- main.cj # 程序主入口

cjpm/src/command 目录下可以逐一找到对应子命令的实现文件：init.cj、build_script.cj、check.cj、run.cj、test.cj、install.cj、uninstall.cj、clean.cj、update.cj、tree.cj等，与 README 所述“模块初始化、依赖检查与更新、统一编译入口”的能力一一对应。另外需要特别注意指南中的一个关键事实：cjpm的产物类型是静态库、动态库和可执行二进制；如需完成 OpenHarmony 的 HAP/APP 构建打包，还需要配合 DevEco Studio 提供的DevEco Hvigor工具使用。cjpm自身就是一个cjpm模块，仓库中自带 cjpm/cjpm.toml，因此可以直接用 SDK 中的cjpm来编译它（自举）。

cjfmt 与 cjlint：格式化与静态检查

cjfmt（Cangjie Formatter）负责代码的缩进、空格与换行调整。其开发者指南 cjfmt/doc/developer_guide_zh.md 给出了六层架构：命令行参数管理 → 配置管理（cjfmt/config/cangjie-format.toml 定义缩进宽度、行宽限制、换行风格等）→ 输入模块 → 源码编译（调用仓颉编译器前端完成词法/语法分析与 AST 构建）→ 格式化（遍历 AST 节点生成 Doc 中间结构）→ 输出模块（覆写原文件或输出到新目录）。从 cjfmt/include/Format 的头文件布局可以印证：NodeFormatter/下近百个头文件负责“AST 节点转 Doc 结构体”，DocProcessor/负责“Doc 结构体转源码”，两者共同构成格式化核心。

cjlint（Cangjie Lint）是基于仓颉语言编程规范开发的静态检查工具，帮助开发者写出满足 Clean Source 要求的仓颉代码（见 cjlint/doc/developer_guide_zh.md）。其源码分为main.cpp、checker（检查引擎）、common（公共模块）、rules（规则实现）四部分。规则以 JSON 形式外置于 cjlint/config 目录，例如structural_rule_G_SYN_01.json（结构/语法类）、dataflow_rule_G_CHK_03.json（数据流类）、exclude_lists.json（排除列表）以及总控的cjlint_rule_list.json，规则编号（如G_SYN、G_SEC、G_FIO）与文件名一一对应，便于按规范条目检索具体检查逻辑。

cjcov 与 cjprof：覆盖率与性能分析

cjcov（Cangjie Coverage）是基于仓颉语言编程规范开发的代码覆盖率工具，用仓颉语言实现（入口 cjcov/src/main.cj，模块定义 cjcov/cjpm.toml）。其 cjcov/src/core 目录下的parsecov.cj（覆盖率数据解析）、genreports.cj（报告生成）、template.cj等文件，从源码结构看构成了“解析覆盖率数据 → 按模板生成报告”的处理链路。

cjprof（Cangjie Profile）用于对仓颉程序进行 CPU 热点函数采样并生成统计报告或火焰图，同时支持导出与分析堆内存（见 cjprof/doc/developer_guide_zh.md）。从 cjprof/src/main.cpp 的帮助文本可以确认其命令集：

Usage: cjprof [--help] COMMAND [ARGS] The supported commands are: -v Print version of cjprof heap Dump heap into a dump file or analyze the heap dump file record Run a command and record its profile data into data file report Read profile data file (created by cjprof record) and display the profile

其中record/report在 Linux 平台生效，对应的 cjprof/src/Commands、cjprof/src/Recorder、cjprof/src/Reporter 目录分别承载命令分发、采样记录（含LinuxRecorder.h）与火焰图/平面报告生成；cjprof/tests 中提供test_cjprof_smoke.cpp、test_cjprof_expand.cpp等测试用例可验证基本流程。

cjcompat 与 cjhead：兼容性检查与头文件生成

cjcompat（Cangjie Compatible）是基于仓颉语言Library Evolution规范开发的 ABI/API 兼容检查工具：输入是两个版本的仓颉库.cjo文件，输出是兼容性差异报告。从 cjcompat/src 的模块划分可以印证其工作流：CjoLoader（.cjo解析）→Diff（AST 差异识别）→CheckersAndRules（检查规则，如AddedDeletedDecls.cpp、ModifiedMemberFunc.cpp）→Logger（结果输出）→Option（命令行选项）。此外，cjcompat/doc/library_evolution_spec 目录随仓库提供了模块演进兼容性规范文档，是理解其检查规则的依据。

cjhead（Cangjie Head）是仓颉 header file 生成工具：扫描仓颉源文件并生成对应的.cj.d头文件（见 cjhead/doc/developer_guide.md）。它出现在 README_zh.md 的目录结构中，文档中给出了明确的导出规则：无修饰符或public修饰的package默认对外可见、protected包内满足条件的 API、无修饰符或public的import、public修饰的全局macro等会被导出到生成的头文件中。

lsp：DevEco Studio 的语言服务后端

lsp（cangjie language server）是在 DevEco Studio 上提供仓颉语言服务的服务器后端，需搭配 DevEco Studio 客户端使用（见 cangjie-language-server/doc/developer_guide_zh.md）。工程最终编译为名为LSPServer的可执行文件。其能力清单在开发者指南中列得很完整：代码补全、定义跳转、悬浮提示、语法高亮、代码诊断、重命名。从 cangjie-language-server/src 的结构可以进一步印证：

cangjie-language-server/src |-- json-rpc # 解析处理 LSP 协议（URI、Transport、Protocol 等） |-- languageserver | |-- capabilities # LSP 特性：completion/definition/hover/rename/diagnostic... | |-- common # 基础功能 | |-- index # 符号索引 | `-- logger # 日志 `-- launcher # 启动和初始化（main.cpp）

cangjie-language-server/src/languageserver/capabilities 目录下的子目录（completion、definition、hover、rename、diagnostic、semanticHighlight、reference等）与上述能力一一对应，且 cangjie-language-server/test 提供了按特性组织的消息级测试（test/message下每个特性均有.base/.test报文对），可以验证各 LSP 特性的输入输出行为。

hle 与 cjtrace-recover：互操作代码生成与堆栈还原

hle（HyperlangExtension）是仓颉调用 ArkTS 互操作代码的模板自动生成工具。其输入是 ArkTS 接口声明文件（后缀.d.ts或.d.ets），输出为包含BUILD.gn文件和src文件夹的目录，src中的.cj文件即生成的互操作代码，同时还会输出包含 ArkTS 文件全部信息的 JSON 文件（见 hyperlangExtension/doc/developer_guide_zh.md）。从 hyperlangExtension/src 的模块划分看：dtsparser（ArkTS 接口文件解析并生成中间层 JSON 描述）、entry（工具参数解析和保存）、tool（ArkTS 接口转换为仓颉接口），与文档描述的“参数解析 → 接口解析 → 抽象描述生成 → 代码生成”流程一致；hyperlangExtension/tests 中cases/（输入用例）与expected/（期望产物）目录可用于对照验证生成效果。

cjtrace-recover用于还原混淆过的异常堆栈信息：当仓颉应用编译时开启外形混淆，运行时抛出的异常堆栈中的函数名与路径名都会被混淆，该工具可以还原这两类信息（见 cjtrace-recover/doc/developer_guide_zh.md）。其实现是仓颉与 C 的混合：命令行主体为 cjtrace-recover/src/cjtrace-recover.cj，符号还原部分通过 cjtrace-recover/src/native/DemangleWrapper.cpp 桥接调用 demangle 能力，而仓库级的 demangle 库源码位于 third_party/demangler。

三、目录结构与组织规范

README_zh.md 给出了仓库顶层目录结构，每个工具目录遵循高度一致的规范：build（构建脚本）、doc（构建指南与使用指南）、src（源码），按需增加config（配置）、figures（架构图）、include（C++ 头文件）、tests（测试用例）等。对照仓库实际内容，这一规范在各工具中得到了一致执行，例如：

. ├── cangjie-language-server # build/build.py, doc, generate/index.fbs, src, test ├── cjcompat # build, doc(含 library_evolution_spec), include, src ├── cjcov # build, doc, src（仓颉语言实现，含 cjpm.toml） ├── cjfmt # build, config(cangjie-format.toml), doc, include, src ├── cjhead # build, config(config.ini), doc, fmt, include, src ├── cjlint # build, config(规则 JSON), doc, src ├── cjpm # build, doc, src（仓颉语言实现，含 cjpm.toml） ├── cjprof # build, doc, figures, include, src, tests ├── cjtrace-recover # build, cmake, doc, src └── hyperlangExtension # build, doc, src, tests

从源码结构看，各工具的构建脚本统一收敛到各自build目录下的build.py（如 cjpm/build/build.py、cjlint/build/build.py、cangjie-language-server/build/build.py），以 Python 脚本驱动 CMake/编译流程，形成工具链内部统一的构建入口约定。

四、构建依赖与构建方式

前置依赖：仓颉 SDK

命令行工具构建统一依赖仓颉SDK，构建方式以 cangjie_build 仓库的 SDK 集成构建指南为准（见 README_zh.md “构建依赖”一节）。不同工具对依赖的侧重略有差异，结合各工具开发者指南可以归纳为：

• 仓颉语言实现的工具（cjpm、cjcov、cjtrace-recover、hle）：需要cangjie SDK及其配套的stdx二进制库，stdx路径需配置到环境变量CANGJIE_STDX_PATH；如需交叉编译 Windows 产物，还可能需要基于 msvcrt 的llvm-mingw工具链（配置到MINGW_PATH）。
• C++ 实现的工具（lsp、cjfmt、cjlint、cjcompat、cjprof）：需要clang或gcc编译器，并配置CANGJIE_HOME指向cangjie SDK位置，因为它们直接链接仓颉编译器前端产物。
• cjtrace-recover额外要求cmake3.16.3 及以上版本和Ninja构建工具。

以cjpm为例，cjpm/doc/developer_guide_zh.md 给出了两条典型构建路径：

1. 使用 SDK 中的cjpm自举编译：

cd ${WORKDIR}/cangjie-tools/cjpm cjpm build -o cjpm # 产物位于 cjpm/target/release/bin/cjpm（Windows 为 cjpm.exe）

2. 使用build.py脚本编译，并支持 Linux 交叉编译 Windows 产物：

cd ${WORKDIR}/cangjie-tools/cjpm/build python3 build.py build -t release --target native # 本机构建 python3 build.py build -t release --target windows-x86_64 # Linux 交叉编译 Windows 产物

其中-t, --build-type可选debug/release，脚本构建的产物输出到cjpm/dist/目录。

五、第三方开源软件与语言服务的索引存储

README_zh.md 以表格形式声明了工具链使用的三个开源组件，完整的来源与构建说明在 third_party/README.md 中：

从源码可以印证语言服务对 Flatbuffers 的使用：cangjie-language-server/generate/index.fbs 定义了IdxFormat命名空间下的索引表结构（Position、Location、CompletionItem等），文件标识为CJID，正是语言服务将编译器符号数据序列化为二进制索引的格式定义。从源码结构看，SQLite 承担索引持久化（cangjie-language-server/src/languageserver/index 下的IndexDatabase、IndexStorage等模块），JSON for Modern C++ 则用于 LSP 报文（json-rpc模块）的解析与封装。

六、开源协议与延伸阅读

本项目基于 Apache-2.0 with Runtime Library Exception 协议开源（见 LICENSE 与 README.OpenSource 声明）。

如需深入某个工具的构建步骤、命令行参数与使用细节，建议按以下路径继续阅读各工具自带的开发者指南：

• 项目管理与构建：cjpm/doc/developer_guide_zh.md
• 语言服务：cangjie-language-server/doc/developer_guide_zh.md（另有 user_guide_zh.md 用户指南）
• 格式化：cjfmt/doc/developer_guide_zh.md
• 静态检查：cjlint/doc/developer_guide_zh.md
• 覆盖率：cjcov/doc/developer_guide_zh.md
• 性能分析：cjprof/doc/developer_guide_zh.md
• 兼容性检查：cjcompat/doc/developer_guide.md
• 头文件生成：cjhead/doc/developer_guide.md
• 互操作代码生成：hyperlangExtension/doc/developer_guide_zh.md
• 堆栈还原：cjtrace-recover/doc/developer_guide_zh.md

总体而言，cangjie_tools以“一个仓库、九大工具、统一build.py构建入口、按工具隔离目录”的方式组织仓颉语言的工程化工具集：命令行工具与 C++ 工具各依其实现语言复用仓颉 SDK 与编译器前端能力，第三方组件仅服务于语言服务的索引存储链路。掌握本文所述的目录规范与依赖关系后，读者可以按各工具doc目录中的开发者指南独立完成任一工具的构建与使用。

• 开发工具
• CLI
• 代码质量