CodeGraph ArkTS 中文快速说明

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

如果你搜索的是下面这些方向，这个 fork 就是对应的能力面：

• ArkTS 代码智能 / 代码图谱
• HarmonyOS / 鸿蒙 项目检索
• ArkUI 语义检索 / 声明式 UI 检索
• 面向 Claude Code / Codex CLI / Cursor 的 MCP 代码智能
• ArkTS、TS、Rust、C++ 混合工程导航

这份中文 README 当前是面向使用者的精简版，不是对英文 README.md 的逐段全量同步。它优先保留：

• 这个 fork 相比上游新增了什么
• 为什么它对 ArkTS / HarmonyOS / 声明式 UI agent 工作流有价值
• agent / MCP 的推荐用法
• 发布、验证、使用边界

如果你需要完整的命令参考、支持矩阵、框架覆盖、库接口、配置项、平台与语言列表，请看英文 README.md。

相比上游新增了什么

• ArkTS .ets 一等公民支持，而不是复用 tree-sitter TypeScript 路径
• 通过 npm 依赖集成 ArkAnalyzer，安装后直接可用
• HarmonyOS Stage model 关键语义支持
• @Entry / @Component / @ComponentV2 / @Builder / 核心状态装饰器可查询
• module.json5 与 ability / extension / form 入口关联可见
• codegraph_context(mode='task') 这类 LLM-first 低噪声导航输出
• ArkTS -> TS -> Rust / C++ 的已验证桥接链路
• 打包 / 安装 / MCP 闭环加固，覆盖 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
• 它主要解决的就是“到底是哪一个页面、组件、状态对象或处理函数在真正负责这个功能”这个第一跳问题

面向 Agent 的默认检索协议

• 实现、调试、改动类任务，默认先用 codegraph_context(mode='task')
  • 目标是先收敛真实 owner、改动入口、状态对象、bridge 目标
• 架构理解、陌生子系统摸底这类更宽的问题，用普通 codegraph_context
  • 目标是先拿到更宽的结构图，而不是最窄的一跳
• 第一跳之后，只补一次结构化 follow-up 来解决最后一个主要未决项
  • 路径不清楚，用 trace
  • 符号职责或源码位置不清楚，用 node
  • 改动接缝或影响面不清楚，用 callers / callees / impact
• rg、grep、直接读文件，只用于精确字面量、资源 key、可见字符串，或者已经完成结构收敛之后的事实确认
• 当 target、owner、chain、boundary 已经足够做决策时就停止，不要为了“更安心”继续扩上下文
• 不要把 CodeGraph 当成关键词大搜循环来用。它的价值是先缩小决策空间，再确认精确事实

可直接复制给 Agent 的协议

适合放进使用方项目的 AGENTS.md / CLAUDE.md / CONTEXT.md：

## CodeGraph Retrieval Default

- implementation / debugging / change tasks: start with `codegraph_context(mode='task')`
- broad architecture / subsystem orientation: start with plain `codegraph_context`
- after the first hop, allow only one structural follow-up for the main remaining uncertainty:
  - `trace` for path / flow uncertainty
  - `node` for symbol / source uncertainty
  - `callers` / `callees` / `impact` for seam / blast-radius uncertainty
- use `rg` / grep / direct file reads only for exact literals, resource keys, visible strings, or after the structural path is already narrowed
- stop when target, owner, chain, and boundary are sufficient
- do not use CodeGraph as a keyword grep loop; use it to narrow the decision space first

如果你想直接给模型一段更短的工作协议，可以用这个版本：

Use CodeGraph structurally, not as grep.

For implementation, debugging, or change tasks:
1. Start with codegraph_context(mode="task")
2. Ask at most one structural follow-up:
   - trace for path
   - node for symbol/source
   - callers/callees/impact for seam or blast radius
3. Use rg/read only for exact literals or after structural narrowing
4. Stop when target, owner, chain, and boundary are sufficient

角色默认法

• planner
  • 先用 codegraph_context(mode='task') 找真实 owner 和边界
  • 再补最多一次结构化 follow-up，就进入计划书写
• coder
  • 先消费 plan 已经给出的 anchors
  • 只在需要确认本地改动接缝时再用 node / trace
  • 除非 plan 被现实代码直接推翻，否则不要重新打开大范围探索

这个 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
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++ 的桥接定位
• 希望通过标准 npm 依赖分发 ArkTS 能力的团队内工具链