CodeGraph ArkTS 中文快速说明

@agentllm/codegraph-arkts 是基于开源 CodeGraph 的长期 fork，面向 ArkTS / HarmonyOS 与 LLM-first agent 工作流做了增强。CLI 名称仍然保持为 codegraph。

英文完整说明见 README.md。

相比上游新增了什么

• ArkTS .ets 一等公民支持，而不是复用 tree-sitter TypeScript 路径
• vendored ArkAnalyzer，安装后直接可用，不依赖外部单独安装 analyzer
• HarmonyOS Stage model 关键语义支持
• @Entry / @Component / @ComponentV2 / @Builder / 核心状态装饰器可查询
• module.json5 与 ability / extension / form 入口关联可见
• codegraph_context(mode='task') 这类 LLM-first 低噪声导航输出
• ArkTS -> TS -> Rust / C++ 的已验证桥接链路
• 打包 / 安装 / MCP 闭环加固，覆盖 vendored ArkTS 工具链

为什么要做这个 fork

• 声明式 UI 对 LLM 的难点不是 ArkUI 独有，Compose、SwiftUI 这类模型也有同样的问题：状态驱动重组、真实 owner 不直观、导航关系不总是直接写在调用链上
• 在鸿蒙声明式 UI 里，一个功能经常被拆散在 UI builder、状态更新、导航、生命周期和 bridge 层里
• 常见的失败方式很直接：找到了页面壳子却没找到处理函数，找到了点击处理却没找到状态对象，找到了状态写入却没找到读取方，找到了 UI 代码却没找到 bridge 目标
• 如果没有框架感知的检索，LLM 往往要反复 grep / read 很多轮，最后还是可能找不全真正负责这个功能的页面、组件、状态对象或处理函数
• 这个 fork 的目标，就是让这些应用级信号能通过同一套 CodeGraph 检索面更容易被找出来

不同角色通常需要什么

• planner：先找到真正负责这个功能的页面、组件、状态对象或处理函数，再看主流程和导航边界
• coder：先找到改动入口、下游 consumer、bridge 目标
• reviewer：先看到影响边界、V1/V2 混用风险、废弃 API 替换路径
• architect：先看到真实应用边界、bridge 形状、分层热点
• diagnose：先看到 source of truth、状态失效路径、生命周期断点

codegraph_context(mode='task') 的目的

• 这是这个 fork 面向实现任务的一跳低噪声上下文入口
• 它先给 LLM 一个可用起点，再决定是否继续做更宽的探索或显式 trace
• 它主要解决的就是“到底是哪一个页面、组件、状态对象或处理函数在真正负责这个功能”这个第一跳问题

这个 fork 怎么补位

• 把 ArkTS 和 HarmonyOS 结构信息变成一等可检索事实
• 在普通调用链不够时，补 ArkUI 感知的导航和合成执行边
• 让 ArkTS、TS、Rust、C++ 之间的 bridge 路径可见
• 把打包、安装、MCP 使用链路补齐，让 ArkTS 工具链开箱可用

快速开始

1. 安装

npx @agentllm/codegraph-arkts

如果你希望全局安装 CLI：

npm install -g @agentllm/codegraph-arkts

安装后命令名仍然是：

codegraph

2. 初始化项目

cd your-project
codegraph init -i

这会创建 .codegraph/ 索引并初始化项目级知识图谱。

3. 作为 MCP 使用

如果你的 agent 通过 MCP 接入，启动方式是：

codegraph serve --mcp

它使用的是 stdio MCP，不是 HTTP 常驻服务。通常由 Claude Code、Codex CLI、Cursor、opencode、Hermes Agent 等客户端拉起。

4. 直接用 CLI

codegraph status
codegraph init -i
codegraph install
codegraph uninstall
codegraph serve --mcp

ArkTS 范围说明

当前已覆盖的 ArkTS P0/P1 能力主要包括：

• Stage model 入口识别
• @Entry / @Component / @ComponentV2 组件语义
• build() / @Builder
• 核心状态装饰器
• module.json5 声明关联
• ability / extension / form 的关键入口与关联
• 混合项目中的 ArkTS -> TS -> Rust / C++ 桥接导航

当前约束：

• ArkTS 文件后缀按当前能力主要面向 .ets
• module.json5 是当前 HarmonyOS 配置侧的主要接入面
• Want / IPC 当前是“存在性 + 关系链”级别，不是完整跨进程传播图
• 更完整的事件/数据精确传播图不属于当前默认范围

给 agent 的使用建议

• 先用 codegraph_context 的 mode='task'
  • 适合实现导向任务，还不知道准确入口点时
• 再用 codegraph_trace
  • 适合端点已知后的显式路径确认
• 用 codegraph_context
  • 适合更宽的任务级结构理解
• 用 codegraph_impact
  • 适合改动前看影响范围

验证命令

常规发布前验证：

npm run build
npm run verify:arkanalyzer-vendor
npx vitest run __tests__/release-packaging.test.ts
npm run verify:arkanalyzer-pack-install
npm run verify:global-install-mcp
npm test

如果需要验证“重新全局安装”这条更慢的路径：

npm run verify:global-reinstall-mcp

注意：

• verify:arkanalyzer-pack-install 和 verify:global-install-mcp 这两个脚本要串行执行，不要并行跑
• verify:global-install-mcp 当前做的是已安装 CLI + 已安装 MCP + Codex install/uninstall/reinstall 的真实闭环
• 其他 agent 目标当前以 installer 结构化测试为主，不是全部都做 live 客户端联调

当前这轮发布候选的额外说明：

• ArkTS 增量 sync 主路径已经做了 RSS 稳定化
• 在针对产品路径的 medium refresh 诊断里，RSS 漂移已经下降到低个位数
• 仓库内 synthetic benchmark 仍然保留一个 medium repeated-refresh 的 headline gap
• 这个 gap 当前被归类为 benchmark / harness 对齐问题，作为下一版本增强处理，不再继续扩大本轮发布风险

适合什么场景

• 中文语境下的 AI coding agent 辅助检索
• ArkTS / HarmonyOS 项目的代码导航和上下文收敛
• 混合项目里 ArkTS 与 TS / Rust / C++ 的桥接定位
• 不想单独维护外部 ArkAnalyzer 安装的团队内分发