# 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](./README.md) 的逐段全量同步。它优先保留：

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

如果你需要完整的命令参考、支持矩阵、框架覆盖、库接口、配置项、平台与语言列表，请看英文 [README.md](./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`：

```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
```

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

```text
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. 安装

```bash
npx @agentllm/codegraph-arkts
```

如果你希望全局安装 CLI：

```bash
npm install -g @agentllm/codegraph-arkts
```

安装后命令名仍然是：

```bash
codegraph
```

### 2. 初始化项目

```bash
cd your-project
codegraph init -i
```

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

### 3. 作为 MCP 使用

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

```bash
codegraph serve --mcp
```

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

### 4. 直接用 CLI

```bash
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`
  - 适合改动前看影响范围

## 验证命令

常规发布前验证：

```bash
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
```

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

```bash
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 能力的团队内工具链