# @c4a/context-cli 中文文档

规范地址：https://npmcn.com/package/%40c4a/context-cli/

版本：0\.7\.95
npm 元数据更新时间：2026-11-08T16:28:30.245Z
中文译文更新时间：2026-11-08T22:42:21.838Z
软件包许可：MIT

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

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

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

- 包体积（解压后）：18.6 MB，881 个文件
- 模块格式：ES Module
- TypeScript 类型：未声明
- Node.js 要求：\>=20
- 运行依赖：34 个
- 首次发布：2026-04-28T06:09:12.517Z
- 最新版本发布：2026-11-08T16:28:29.914Z
- 近 30 天下载量：7974（2026-10-09 至 2026-11-07，npm 官方下载统计）
- 已发布版本数：121（近 12 个月 121 个）

## 中文简介

可追踪知识生产的地方运行时间和代理整合

## 安装

```sh
npm install @c4a/context-cli
```

也可以使用：`pnpm add @c4a/context-cli`、`yarn add @c4a/context-cli`、`bun add @c4a/context-cli`

## README

# Context Agent 运行时

## 仓库证据插件

新建工作区位于 Git 根目录（或尚无上级 Git 仓库）时，初始化会附带 `context-evidence.sourcegraph.wasm`。存量工作区运行 `context evidence install [project-dir] --format json`；嵌套工作区需显式指定 `--repository-root <git-root>`（全仓托管）或 `--plugin-root <登记内容根目录>` （范围托管），远程读取的 `workspace_root` 是工作区相对插件目录的位置。 未知或用户修改的同名文件会保留，不自动提交或推送。

制品正常提交并同步后，兼容的只读 MCP 宿主可在 read/read\_many 中传 `plugins: [{"name":"context-evidence"}]`，随正文返回登记的章节来源。 这不表示已经复核原始来源，也不改变本地查询或生产流程；增强不可用时保留原读取路径。 使用者无需安装 Rust。参见[插件 ABI 与构建说明](https://npmcn.com/package/%40c4a/context-evidence-wasm/README.md)。

[English](https://npmcn.com/package/%40c4a/context-cli/README.md)

`@c4a/context-cli` 提供 Context 知识生产工作流的本地运行时和 Agent 接入。虽然 包名中包含 CLI，但它面向用户的主要体验不是终端命令清单：用户调用生产 入口，用自然语言说明要生产的知识，再在对话中完成必要决策。

运行时执行确定性工作，包括观察工作区、采集来源、索引代码、校验证据、暂存候选、 应用审核决定、验证质量和构建知识包；Agent 负责语义工作，用户负责权限和重要内容 决定。运行时本身不会调用 LLM。

## 安装 Agent 接入

```bash
npm install -g @c4a/context-cli@latest
context plugin install # 全局安装
# 或者，只安装到仓库：
context plugin install --local /path/to/repo --agent auto-detect
```

源码仓库本身也是插件市场。Claude Code 与 Codex 可以从中安装 `c4a` 插件：`claude plugin marketplace add context4ai/context` 后执行 `claude plugin install c4a@c4a`，或 `codex plugin marketplace add context4ai/context` 后执行 `codex plugin add c4a@c4a`。CLI 仍需安装，插件把工作流和随包的 Indexer 交给它执行。

`--local` 必须显式搭配 `--agent`：`claude`、`cursor`、`codex`、`all`、`auto-detect` 或 `standalone`。路径为仓库根；指定宿主直接写入对应 `.claude`、`.cursor`、`.agents` 子目录，不检测是否安装宿主。`all` 全装；只有 `auto-detect` 检测目标仓库已有的 `.claude`、`.cursor`、`.agents` 目录，不检测 PATH 或桌面应用；均不存在时兜底 `.agents/skills`。`standalone` 则直接写入 `<path>/skills`，不生成 commands 或宿主子目录。均支持 `--dry-run`，不改全局配置。

从 0.7.20 迁移：裸 `--local` 补充 `--agent auto-detect`；指定宿主时传仓库根，不再传宿主目录。全局安装不变。自动探测不代表宿主已加载，安装后需刷新宿主。

| 命令 | 局部目录与行为 |
| --- | --- |
| `context plugin install --local /path/to/repo --agent claude` | `commands/` 放公开入口；`skills/` 放其他技能，内部技能设置 `user-invocable: false`，不重复安装入口 Skill |
| `context plugin install --local /path/to/repo --agent cursor` | `commands/` 使用随包的 `c4a-*` 命令；`skills/` 放其他技能，不保证隐藏 Provider 的菜单入口 |
| `context plugin install --local /path/to/repo --agent codex` | 全部入口保留为 skills，保留随包的 `agents/openai.yaml` 调用策略，不生成无效的 `commands/` |

宿主必须支持发现目标位置。局部入口没有插件命名空间。`--dry-run` 只预览；重复安装仅刷新本命令管理且未被修改的内容，保留无关文件；同名自定义内容或本地修改会报冲突。已有通用 skills 目录切换为 command 宿主时，请选择新目录，避免重复入口。`plugin status` 仍只检查全局宿主状态。调用元数据控制宿主入口展示/自动调用，不是 CLI 权限或安全隔离。

安装后重启或刷新 Agent 宿主。全局安装会生成一个带宿主命名空间的 Context 主入口， 并把 `context-code-indexer`、`context-markdown-indexer` 作为无命名空间的生命周期 Provider Skill 投影到 Claude、Codex 和 Cursor 的用户技能目录。

生产入口是 `/c4a:context`。它可以创建用户请求的工作区、定位已有工作区， 或从当前状态继续流程。其他公开入口是 `/c4a:context-plan`、 `/c4a:context-inspect-search` 和 `/c4a:context-repo-content`（Cursor 中为 `/c4a-context-*`），详见[插件契约](https://npmcn.com/package/plugins/context/README_CN.md)。用户应该从知识意图开始，而不是内部命令：

```text
/c4a:context 请把这些产品文档和当前仓库整理成经过审核的 Agent 知识包，所有代码
结论都要保留可追溯引用。
```

如果 Agent 入口已经存在但缺少 `context` 可执行文件：宿主已允许升级到最低版本时， 入口会安装一次；否则给出准确的安装恢复方法并停止。它不会为每次调用增加安装预检，也不会把普通工作流中的 `not found` 诊断误判成可执行文件缺失。

## 飞书读取身份

`CONTEXT_LARK_IDENTITY=user|bot` 控制飞书来源采集，默认 `user`。每次执行 Context 命令的 shell 都需传入该环境变量；仅在提示词中写配置并不会自动导出环境变量。 `bot` 模式先使用应用身份，遇到凭证、scope 或访问权限错误时回退当前用户一次， 本次采集后续分页、引用与资源下载沿用回退身份。网络、限流和解析错误不切换身份。 该配置不扩大来源授权或知识产物可见范围；托管运行时的用户授权遵循宿主流程。

## 一个 Agent 入口如何驱动整套工作流

```text
用户知识目标
     ↓
单一 Agent 入口
     ↓
context entry ── 观察工作区位置和状态
     ↓
workflow.current ── 当前 Route、资源、Gate 和精确命令
     ↓
Agent 阅读 / 判断 / 执行一个选中动作
     ↓
工作区事实变化 ── 再次求值
```

`context entry --format json` 是只读的启动解析器，可以返回初始化动作、进入已有 工作区的动作，或当前工作流求值。不存在 `context continue` primitive，也不会为 source、review、build 或 status 提供第二个公开入口。

工作区就绪后，`workflow.current` 是当前步骤的权威协议：

-   执行动作前完整读取所有标记为 `read-required` 的必需资源；
-   只执行 Route 返回的命令，并保留 revision 和 authority 参数；
-   人工 Gate 先解释用户在决定什么以及影响范围，再收集选择；
-   项目配置修改只发生在 Route 指定的文件中；
-   每个动作后重新观察事实，过期命令不能推进已经变化的工作区。

长篇操作说明、Schema、诊断和来源视图继续作为 Workflow Provider 中可寻址的文件。 Agent 只加载当前 Route 选择的内容，不把完整生命周期长期塞在 Prompt 中。

## 知识生产生命周期

| 阶段 | 用户体验 | 运行时保护内容 |
| --- | --- | --- |
| 目标和来源 | 确认要生产什么知识、哪些资料属于范围 | 来源身份、权限边界、固定的仓库或文档输入 |
| 采集和提取 | Agent 阅读文档或检查已确认的代码边界 | 完整正文、资源、符号、关系、指纹和新鲜度 |
| 结构和编译 | 审阅知识组织方式和候选正文 | 绑定来源的 Node/Section、覆盖度、连续性和稳定身份 |
| 审核和关闭 | 批准、拒绝或调整候选 | 原子化审核应用、持久决定和关闭后的结构投影 |
| 验证和构建 | 选择产物并得到可复用知识包 | 质量校验、知识包模板、资源策略和构建清单 |

构建完成的是当前正式状态，不会冻结工作区。以后新增或变化的来源可以开启下一轮 知识生产。

## 普通对话与全托管对话

普通模式是默认模式，保留显式的来源、范围、结构、审核和知识包决定，并可在内容 审核 Gate 提供 HTML 检查报告。

只有用户在当前对话明确授权全托管时，Agent 才使用：

```bash
context run --managed --until blocked-or-complete --format json
```

它会合并连续的确定性动作和可 delegated 的 Gate；遇到 Agent 阅读、项目配置、 额外权限、诊断修复或非唯一计划时立即停止。它复用同一张 Workflow Graph，不会 删除普通模式的审核能力。授权只对当前对话生效，不会持久化，也不能授权新的来源 边界、未读取外部内容、仓库操作、失败的校验或失败的验证。

## 工作区状态

```text
context/
├── src/                         # 声明式项目配置和知识包模板
├── sources/                     # 来源登记和采集证据
├── knowledge/                   # 正式 Markdown 和持久决定
├── dist/                        # 构建产物
└── .tmp/context-runtime/
    ├── lifecycle/               # 当前轮候选和结构
    ├── debug/                   # 可选调试轨迹
    └── logs/                    # 可选运行事件 outbox
```

这些目录具有不同的持久性契约。`sources/` 和 `knowledge/` 是项目状态，`dist/` 是 可重复构建产物，lifecycle 和 debug 目录是被忽略的运行状态。任务暂存区在成功交付后 按工作区准备指引清理，不在 close 后立即清空。不要通过手工编辑或删除 CLI-owned 状态修复流程， 应执行当前 Route 返回的恢复动作。

## 证据和安全边界

-   登记来源不等于授权读取来源正文。
-   运行时不会静默在来源仓库中 clone、checkout、reset、fetch、install、build、 test 或运行脚本。
-   Markdown 解析只保留结构证据，不推断产品含义，也不选择知识分类。
-   代码提取只生成结构事实；知识含义和范围由 Agent 与用户决定。
-   `source_ref` 是不透明、可验证的证据身份，应完整复制，不能当作文件路径解析。
-   审核决定只能通过原子化 review apply 变成正式 Markdown；Agent 不手写生命周期 产物。
-   知识包模板只决定分发形态，不会替代正式知识成为事实来源。

## 知识包产物

声明好的知识包构建到 `dist/<package-name>/`。Agent 知识包可以包含 `wikis/`、 `guides/`、`rules/`、`feats/`、Skills、索引和包专属检索工具；LLM 包则把所选 知识聚合为一个文本产物。

每份构建清单都会将分发路径映射回工作区正式知识。资源可以使用仓库 raw URL、 显式 URL 前缀或随包分发；项目在构建前选择策略。

详见 [Package Outputs](https://npmcn.com/package/%40c4a/context/docs/guides/package-outputs.md) 和 [Package Templates](https://npmcn.com/package/%40c4a/context/docs/reference/package-templates.md)。

## 诊断和直接使用 CLI

普通用户应跟随 Agent 入口。直接命令继续供维护、自动化和诊断使用：

-   `context status --format json` 检查当前 Route；
-   `context <command> --help` 是当前参数的权威来源；
-   `context plugin status` 检查已安装的 Agent 投影；
-   `context debug enable` 在 `.tmp/context-runtime/debug/` 记录可选轨迹；
-   `context revise "<当前候选标题、路径或 id>" --instruction "<修正要求>"` 会在批准前精确重开该候选所属的 Author workset；它不会创建第二套 revision 页面，也不会直接改写正式 `knowledge/`；
-   代码提取先暂存可读的 `codeindex` Candidate，并在 Review 前分别检查输入分析、稳定边界 覆盖、正文密度、证据范围和页面规模；旧 `codegraph` 工作区只通过 Route 返回的 迁移动作升级；
-   `context indexer` 生命周期以内容寻址 ledger 恢复 main/post-author 运行，再由 CLI 根据 current owner、accepted Result 和完整 question-target 集重新计算 coverage； capability/material gap 不能被报告为 complete。ordinal/fixed-count partition 按授权顺序自动重试； 策略耗尽后只允许带持久化前驱的 CLI catalog fallback 生成唯一父单元，不调用 Agent 或用户 Gate；
-   `markdown-provider` Indexer Route 只能从精确 current 的文档 capture 开始。Agent 只报告当前会话可见的 `context-markdown-indexer*` Skill，不持久化 discovery list； CLI 重新计算 Route 与静态校验，自动解析并 stage 精确 CLI-bundled Bundle，外部解析 或本地定制则分别停在显式 Host/customization Outcome；
-   `route-index-requirement-confirmation` 会重新计算 canonical requirement comparator；普通确认 只可使用显式 authority，contraction 或不可比较的义务替换始终进入不可委托人工 Gate。 `validate-subject-key-schemas` 对已有 approved Node 上的 identity-breaking 变化要求 Provider major 与精确 re-identification 授权，漏映射、split、merge 或 collision 在 Gate 前失败；精确 target 命中多个 Node 返回 `index-target-resolution-ambiguous`，非法复用返回 `index-target-resolution-invalid`；
-   未解决的 material question 只保留在 current reconciliation report。新采集的 Markdown 或其他授权材料重新运行普通 main Indexer，并更新同一个 Candidate；不存在第二份 checkpoint、answer-only operation 或 Review Route；
-   主 Candidate Review 要求 current 的 precompile/postcompile audit record。CLI 会复核 requirement、registry、inventory、layout 与 candidate set 绑定；阻塞性的机械失败会重开受影响的 Author 或 Composer workset 后重新编译，建议性的 profile metric 只作为 warning，不建立重试账本或 override Gate；
-   必需 material gap 会阻塞普通生命周期，直到新增 capture 重新运行受影响 workset；普通 `context close` 写入 approved structure；任务清理在成功交付后进行；
-   `context clean-cache --dry-run` 预览 Context-owned 过期插件缓存清理。

绑定 revision 的命令应从 `workflow.current` 原样复制；文档示例只用于理解入口， 不能替代当前 Route。参见[安装后快速说明](https://npmcn.com/package/%40c4a/context-cli/docs/quickstart.zh-CN.md)和 [debug tracing](https://npmcn.com/package/%40c4a/context-cli/docs/debug-tracing.md)。

## 文档与开发

-   [插件契约](https://npmcn.com/package/plugins/context/README_CN.md)
-   [Workflow Provider 内部说明](https://npmcn.com/package/%40c4a/context-cli/context-workflow/README.zh-CN.md)
-   [SDK 文档索引](https://npmcn.com/package/%40c4a/context/docs/README.zh-CN.md)
-   [知识项目完整示例](https://npmcn.com/package/%40c4a/context/docs/getting-started.md)
-   [Agent Guide](https://npmcn.com/package/%40c4a/context/docs/guides/agent-guide.md)
-   [Project API](https://npmcn.com/package/%40c4a/context/docs/reference/project-api.md)

源码、link、打包安装和发布流程参见 [`DEVELOPMENT.md`](https://npmcn.com/package/DEVELOPMENT.md) 以及本包的 [`DEVELOPMENT.md`](https://npmcn.com/package/%40c4a/context-cli/DEVELOPMENT.md)。

```bash
bun run --filter @c4a/context-cli build
bun run --filter @c4a/context-cli typecheck
bun run --filter @c4a/context-cli lint
bun run --filter @c4a/context-cli test
```

构建会在 `dist/plugins` 生成 npm 宿主投影，并在 `../../plugins/context/repo-install` 生成 Git 直装投影；只修改 `../../plugins/context/` 和 Workflow Provider 源码，不要直接编辑生成产物。

## License

MIT.

### 精简状态与配置读取

`context status --view summary --format json` 返回进度和 `next_route.file`，完整可执行 Route 保存在该文件；需要内联完整 Route 时用 `--view full`。`context run --managed --until blocked-or-complete --format json` 默认返回停止摘要、`next_route.file` 和保存完整执行记录的 `result_file`，加 `--verbose` 可展开完整结果。执行下一步前读取所指 Route。

`task_completion` 是当前阶段已接受任务占比，不是整体交付率；任务、主题、页面不能混作同一分母。`pages.authored_not_delivered` 只统计已写出但尚未交付的页面。配置步骤先读完材料并确认读取，再编辑配置，编辑后刷新状态，不执行旧 revision 的读取确认。

### 生产过程中的维护

`context revise <页面> --instruction <要求>` 保留当前批次返修能力；修订其他已批准页面时可登记待办，不覆盖生产账本。`--regenerate` 明确准备当前程序化 API 内容，即使来源版本没有变化；`--timing priority` 请求提前交付已有完整页面，仍保留正常审核。

多页使用 `context task maintain --input <文件> --format json`。输入包含 `id`、`operation`（`revise`、`regenerate` 或 `rebuild`）、可选 `timing`（`after-batch` 或 `priority`），以及 `targets: [{ path, instruction }]`。`rebuild` 不带 targets，只重新打包已批准内容，不完成生产任务。重试复用相同 id 和输入。状态会说明当前维护、待办及等待原因。

来源刷新仍走明确范围调整；该入口不会抓取远端来源，也不代表能够重跑任意自定义 Composer。目标主体仍有未交付生产内容时，先等该写入方完成，再修订最新正文，避免恢复后覆盖。

修订批次（包括来源更新的页面批次）尚未审阅通过时，`revise` 与 `task maintain` 把页面加入该批次而不是排队，`task retire` 把退役安排在该批次一并生效。审阅通过即关闭批次，之后的请求排到下一批。通过后、交付完成前，不经再次审阅的机械修正用 `context task record-fix --input <{path, reason}> --format json` 记录。

`context task maintenance-status --format json` 返回维护状态和 revision。`context task cancel-maintenance <id> --format json` 取消待办；明确放弃活动维护草稿时，再提供当前 `--discard-revision`。已批准页面和其他生产成果保留。

## 常见问题

### @c4a/context-cli 是什么？

可追踪知识生产的地方运行时间和代理整合

### 如何安装 @c4a/context-cli？

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

### @c4a/context-cli 支持 TypeScript 吗？

该包的 package\.json 没有声明类型入口。需要类型提示时，可以在 npm 上查找社区维护的 @types/c4a\_\_context-cli 是否存在。

### @c4a/context-cli 支持 ESM 还是 CommonJS？

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

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

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

### @c4a/context-cli 可以商用吗？

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

### @c4a/context-cli 的下载量有多少？

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

### @c4a/context-cli 还在维护吗？

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