# @ctxo/cli 中文文档

规范地址：https://npmcn.com/package/%40ctxo/cli/

版本：0\.19\.0
npm 元数据更新时间：2026-11-10T16:40:19.093Z
中文译文更新时间：2026-11-11T06:37:29.288Z
软件包许可：MIT

本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40ctxo/cli
原文对照：https://npmcn.com/package/%40ctxo/cli/?lang=original
项目主页：https://github.com/alperhankendi/Ctxo#readme
源码仓库：https://github.com/alperhankendi/Ctxo

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：900 kB，41 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- Node.js 要求：\>=20
- 运行依赖：12 个
- 首次发布：2026-04-12T22:06:53.594Z
- 最新版本发布：2026-11-10T16:40:18.553Z
- 近 30 天下载量：2825（2026-10-11 至 2026-11-09，npm 官方下载统计）
- 已发布版本数：31（近 12 个月 31 个）

## 中文简介

MCP 服务器为代码库提供依赖感、 丰富历史的上下文

## 安装

```sh
npm install @ctxo/cli
```

也可以使用：`pnpm add @ctxo/cli`、`yarn add @ctxo/cli`、`bun add @ctxo/cli`

## README

[![npm version](https://img.shields.io/npm/v/@ctxo/cli.svg)](https://www.npmjs.com/package/@ctxo/cli) [![CI](https://github.com/alperhankendi/Ctxo/actions/workflows/ci.yml/badge.svg)](https://github.com/alperhankendi/Ctxo/actions/workflows/ci.yml) [![Release](https://github.com/alperhankendi/Ctxo/actions/workflows/release.yml/badge.svg)](https://github.com/alperhankendi/Ctxo/actions/workflows/release.yml)

![Ctxo — Code intelligence for AI agents](https://npmcn.com/package/%40ctxo/cli/docs/img/hero-svg.svg)

```Shell
npm install -g @ctxo/cli   # one-time global install (gives you the `ctxo` command)
ctxo init
ctxo index
```

[![Get Started →](https://img.shields.io/badge/Get%20Started-%E2%86%92-06b6d4?style=for-the-badge&labelColor=0f172a)](https://alperhankendi.github.io/Ctxo/docs/)

检测您的语言, 安装合适的插件, 将 Ctxo 线接入您的 AI 客户端, 安装 git 钩子, 并构建第一个索引, 全部在一个命令中 .

* * *

## 问题: 特工代码失明

将现代编码代理器丢入真正的Repo. 它撕裂一个符号, 得到47个点击, 读出五个文件 找到定义, 五个为呼叫者, **完全错过子类** (继承不出现于文本搜索), **从不检查 git 历史** (并自信地重新引入了三周前被还原出的一个bug),然后流出上下文并开始产生幻觉.

这不是一个技能差距。 这是一个 **感官间隙**特工正在浏览你的密码库 闭着眼睛和电话簿.

## 解决办法:积极主动,而不是被动反应

核心移: 您的代理人停止了对文件的反应, 它偶然地进入并开始从完整的地图开始规划 . **编辑前爆炸半径 。 虫子修好前的Git意图. 重命名前的导入者列表 .**

Ctxo 一次将您的回波索引, 由文件监视器和 git 钩子保持新鲜度, 变成一个决定性的图: 每个符号, 每个边缘( 进口, 呼叫, 扩展, 工具, 使用, 以及数据边缘读取, 写出和执行), 每个相关的 git 故意进行分类, 每个反模式 。 全部通过14个语义MCP工具被曝光,外加4个域工具与 `@ctxo/domain`。 。 。 .

一个 `get_blast_radius` 调用替换整个 riggrep/ 读取螺旋 。 一个 `get_pr_impact` 替换“等等,这叫什么?”

特工还写着密码 它只是停止写它 **盲点**,因此bug从不必被编译器,测试,CI,或者用户所捕获.

## 密码库板

Full-stack analytics UI 有8个视图:文件树,热相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相 在每次推力时都部署到GitHub Pages.

![Codebase Dashboard](https://npmcn.com/package/%40ctxo/cli/docs/img/ui.png)

[打开挂板](https://alperhankendi.github.io/Ctxo/ctxo-visualizer.html)

## 依赖性图

`ctxo visualize` 从您生成自定义的 HTML `.ctxo/` 指数。 与PageRank sizing,层色相接,点击时爆炸半径相接,并有暗/光主题.

![Dependency Graph](https://npmcn.com/package/%40ctxo/cli/docs/img/visualize-00-light.png)

[打开依赖图](https://alperhankendi.github.io/Ctxo/visualize.html)

## 安全编辑警卫

AI特工不会因为无法编码而失败. 他们失败了,因为他们的密码是盲的。 Ctxo在他们写出一行之前给他们全貌.

问题:一个代理打开一个文件,进行目标编辑,然后走开. 它从来没有检查什么 其他取决于这个符号。 下游来电者默然相断. 测试通过,因为代理只运行同一文件中的.

安全编辑的护卫 关闭这个循环决定。 当你跑的时候 `ctxo init`,则:

1.  登记a **PreToo 使用钩** 内 `.claude/settings.json` (Claude Code),可以截取每个编辑呼叫.
2.  安装 3 **示范技能** (单位:千美元)`ctxo-understand`, (中文(简体) ), `ctxo-safe-edit`, (中文(简体) ), `ctxo-review-pr`所以特工知道何时可以检查爆炸半径 历史和公关风险.

如果代理试图编辑高影响符号而不首先调用 `get_blast_radius`,钩子会阻断编辑并告诉代理商检查什么。 代理运行工具后,编辑正常进行. 每个会话每个符号一次起火,在任何不确定性上打开失败.

用钩子和技能 做工作,总是负载 `CLAUDE.md` 块缩小为四行 :

```markdown
## ctxo

This repo has a ctxo index: dependency graph, git intent, change health. For structural questions (who depends on X, what breaks if X changes, why X looks like this), use the ctxo MCP tools before grepping.
A pre-edit guard blocks the first edit to a high-impact symbol until `get_blast_radius` has been called for it.
Skills: `ctxo-understand` (orient at task start), `ctxo-safe-edit` (before changing a symbol), `ctxo-review-pr` (before reviewing a diff).
```

其他客户,没有警卫的克洛德密码 还有.. `CLAUDE.md` 另一个客户端也读取( a) `AGENTS.md` 链接)获得完整的工具指南. 重运行 `ctxo init` 替换块并保存文件的其余部分。 块和技能都用Pretier的布局来写,与被忽略的格式比较,因此一个标记下对物质和ctxo从不重写. `ctxo doctor` 警告当块,技能或钩子漂移 `ctxo doctor --fix` 修理它们.

**选择部分 :**

```shell
ctxo init --only rules,skills,guard   # add the guard and the skills; the rules block follows
ctxo init --skip git-hooks            # everything except the git hooks
ctxo init --no-guard                  # does not install the guard (CLAUDE.md gets the full block unless a guard is already registered)
```

**告诉它:**

```shell
# Preview which symbols the guard would flag at current sensitivity
ctxo gate --preview

# Check blast radius for a specific symbol (pipe to jq, CI scripts, etc.)
ctxo blast-radius "src/core/graph.ts::buildGraph::function" --json
```

配置灵敏度 `.ctxo/config.yaml`数字 :

```yaml
gate:
  enabled: true
  sensitivity: balanced   # strict | balanced (DEFAULT) | lenient
```

**平台矩阵 :**

| 平台 | 钩子执法 | 技能 | 规则 |
| --- | --- | --- | --- |
| 克劳德代码 | 是( 前工具使用块) | 对 | 对 |
| 光标 | 没有( 没有屏蔽预编辑钩) | 对 | 对 |
| 其它 | 没有 | 在得到支助的地方 | 对 |

## 每一次行动都新鲜

一个陈旧的索引比没有更糟糕:代理商信任一个不再匹配代码的地图. `ctxo init` 安装运行的后承诺钩 `ctxo index --commit HEAD` 一次每个犯罪。 它只重新索引了执行更改的文件,从 git 历史中刷新了共更改矩阵,并记录了每个执行的漂移和边界信号的一个快照.

```shell
ctxo index --commit HEAD                                 # what the hook runs
ctxo index --files src/a.ts src/b.ts                     # re-index a few files
ctxo index --cochange-commits 500 --cochange-since 12m   # co-change window (or `cochange:` in config.yaml)
ctxo doctor --fix                                        # upgrades an old hook block in place
```

你忘记去碰的文件通常是没有导入点的文件. 不断一起变化的文件是组合的 : `get_blast_radius` 推动一个与目标同步变化的依赖性 `potential` 改为 `likely`,并列出完全没有依赖路径的文件 `coChangedFiles`。 。 。 . `ctxo index --max-history` 仅控制每个文件所保存的数量 `get_why_context`; 共变窗口有自己的设置.

## 边界在哪里

文件夹名称说出一件事;输入和承诺历史常说出另一件事. `ctxo index` 也写入候选的受限上下文: 由依赖和共变边缘组合成的文件, 中心文件被挡住, 每个文件都有建议标签, 凝聚力分数, 顶部名词和交叉到其他候选人的边缘 。 与 `@ctxo/lang-sql` 已安装,表格,观点和程序加入图:一个表格的读者和作者在其爆炸半径内出现,每个候选人列出与其他候选人共用的表格.

```shell
ctxo contexts          # candidates as a table
ctxo contexts --json   # the full contexts-view.json
```

探员们从同一个观点 `get_architectural_overlay(mode: "contexts")`,一名候选人满额 `candidate: <id>`。 。 。 .

## 烂名片

代理修改了代码中的出借规则,描述它们的卡片则保持不变. 在注册簿中指定您所绑定的上下文, Ctxo 检查结构, 绝不意味着: 上下文代码在会话中更改, 没有卡片更新或卡片 `Domain-Unchanged` 承诺拖车,一个没有卡片定义的规则ID,一个不再解决的卡片链接,一个跨越合同外上下文边界的边缘. 选入 `@ctxo/domain` 软件包添加了命令和一个克洛德代码后卫; Ctxo 从不写出牌.

```shell
ctxo install domain                       # the opt-in @ctxo/domain package
ctxo init --domain                        # registry skeleton, fold guard, skill, domain config
ctxo contexts-touched --since origin/main # which named contexts a branch changed, and which are resolved
ctxo verify-domain --since origin/main    # CI gate: registry, cards, rule IDs, loader rules, boundaries, shadow specs
ctxo domain rules --write                 # path-scoped rules that point the agent at the card
ctxo domain discover                      # run first: propose tracker prefixes and test conventions from the repo
ctxo domain shadow-specs lending          # business logic in the lending code that no rule pins yet
ctxo domain map                           # every context with its rung, a suggested rung and what blocks the next one
```

有了纸牌, `ctxo index` 将每项规则与标定规则的测试和执行规则的代码相链接,并且代理在操作时看到规则: `get_blast_radius` 列出可能违反的规则和需要更新的牌, `get_why_context` 他们背后的决定, `get_context_for_task` 一张卡片摘录, `get_pr_impact` 上下文和规则没有经过检验。 四个工具直接回答域问题:

| 工具 | 答复 |
| --- | --- |
| `get_domain_context` | 拥有符号或文件的上下文卡:条款、带有其测试和代码的规则、合同、决定 |
| `get_rule` | 一条规则通过ID: 标出它的测试(以及每个测试是如何找到的) 执行它的符号,它背后的决定 |
| `find_shadow_specs` | 删除测试:在尚未标出规则的上下文中进行字面比较、正常化、重试和超时值、端点和数据对象,每个上下文都有稳定的指纹可以解析 `shadow-specs.yaml` |
| `get_context_map` | 每一个背景 其测试,界限,漂移和开放 候选人, 业主的rung 和一个建议, 标准 |

`get_ranked_context` 与 `scope: "domain"` 搜索所链接的卡片和文件.

见 [Ctxo域公约v1](https://npmcn.com/package/%40ctxo/cli/docs/features/domain-knowledge.md#ctxo-domain-conventions-v1) 用于登记、卡片模板和收养梯子.

## 支持的语言

| 语言 | 插件 | 级别 | 页:1 |
| --- | --- | --- | --- |
| 类型脚本 / Java 脚本 | `@ctxo/lang-typescript` | 满 | ts-morph; 类型意识交叉文件解析; 装饰器作为说明; 测试块作为符号; 已知呼叫站点的 SQL( pg, mysql2, mssql, knex, Prisma, TypeORM, Sequelize, better- sqlite3 原始 SQL) |
| 走开 | `@ctxo/lang-go` | 语法 / 全 | `ctxo-go-analyzer` 完全分层(Go 1.22+),树保姆倒置;结构标记作为说明; `_test.go` 函数为符号( 完整级); 已知呼叫站点的 SQL(`database/sql`, sqlx, pgx, gorm 生; 完整级) |
| C# (韩语) | `@ctxo/lang-csharp` | 满 | Roslyn; . NET SDK 8+ 用于全层倒置的树保姆 |
| 爪哇语 | `@ctxo/lang-java` | 语法 / 全 | 树保姆语法分级内置; 完整分级通过 `@ctxo/lang-java-analyzer` 组件( JRE 11+ 需要, 覆盖 Java 8- 21); 由 `pom.xml` 编号 : `build.gradle`; 两层的说明; 带有说明的测试方法; 已知呼叫站点的SQL( JDBC, Spring) `JdbcTemplate`, JPA 本地查询, MyBatis; 完整级) |
| SQL (T- SQL) (英语) | `@ctxo/lang-sql` | 语法 | `.sql` 表格、视图、程序和功能 `reads` 编号 : `writes` 编号 : `executes` 边缘;不需要数据库或.NET。 随着它的安装, C# 插件的 Roslyn 级还链接了 ATO. NET 的常数 SQL, Dapper, `SqlBulkCopy` 页:1 核心呼叫站点到相同的表格,而TypeScript、Java和Go插件在其已知的呼叫站点也一样 |

通过 CLI 快捷键安装 :

```bash
ctxo install typescript go csharp   # syntax or full tier auto-detected
ctxo install sql                    # T-SQL plugin (alias tsql)
ctxo install domain                 # opt-in domain knowledge layer (@ctxo/domain)
ctxo install java                   # installs syntax tier; adds full-tier analyzer when JRE 11+ detected
ctxo install java --full-tier       # force full-tier analyzer install
ctxo install java --syntax-only     # skip analyzer, syntax tier only
```

## 链接

-   [文档](https://alperhankendi.github.io/Ctxo/docs/):快速起动,MCP工具,CLI参考,集成
-   [无](https://www.npmjs.com/package/@ctxo/cli)
-   [更改日志](https://npmcn.com/package/%40ctxo/cli/CHANGELOG.md)
-   [LLM 参考](https://npmcn.com/package/%40ctxo/cli/llms-full.txt)

## 许可证

麻省理工学院

## 常见问题

### @ctxo/cli 是什么？

MCP 服务器为代码库提供依赖感、 丰富历史的上下文

### 如何安装 @ctxo/cli？

在项目目录运行 npm install @ctxo/cli，或使用 pnpm add / yarn add / bun add。它还提供命令行工具 ctxo，可以用 npx ctxo 直接运行。

### @ctxo/cli 支持 TypeScript 吗？

支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。

### @ctxo/cli 支持 ESM 还是 CommonJS？

以 ES Module 形式发布，推荐使用 import 引入。在 CommonJS 项目中，Node\.js 20\.19\+ / 22\.12\+ 可以直接 require\(\) 不含顶层 await 的 ES Module，更早的版本需要改用动态 import\(\)。

### @ctxo/cli 需要什么版本的 Node\.js？

package\.json 的 engines 字段要求 Node\.js \>=20。版本不符时 npm 默认只给出警告，开启 engine-strict 后会拒绝安装。

### @ctxo/cli 可以商用吗？

@ctxo/cli 使用 MIT 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。

### @ctxo/cli 的下载量有多少？

根据 npm 官方下载统计，@ctxo/cli 在 2026/10/11 – 2026/11/09 这 30 天内被下载 2,825 次，日均约 94 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

### @ctxo/cli 还在维护吗？

最新版本 0\.19\.0 发布于 2026/11/11（今天）；至今共发布 31 个版本，其中过去 12 个月发布了 31 个；首次发布于 2026/04/13。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。