cargo-context

Cargo CLI — 上下文

context 是一个由 Git 支持的仓库，包含类型化的 Markdown/MDX 文件，用于记录工作区的 GTM 知识（公司叙事、ICP、角色画像、策略、案例、异议等），供人类和 Agent 读写。cargo-ai context 领域包含两个子域：

• runtime — 浏览、读取、写入、编辑工作区的运行时沙盒（已检出的 context 仓库副本），并对其执行操作。write/edit 会推送到默认分支，而 execute 会自动提交并推送其命令留下的任何已跟踪工作树更改。
• graph — 构建/加载从 context 仓库中的每个 Markdown/MDX 文件派生出的知识图谱。

context 仓库的规范示例是 getcargohq/cargo-workspaces。写入新条目前，请阅读其 README.md，了解领域布局和文件约定。 对于批量运行中使用的、与运行时无关的文件（CSV、PDF），请改用 cargo-workspace-management（cargo-ai workspaceManagement file upload）上传。 对于附加给 Agent 的 RAG 文件，请使用 cargo-ai（cargo-ai content file upload）。

完整的 context 仓库结构和各领域模板见 references/conventions.md。 各条 cargo-ai context 命令返回的 JSON 结构见 references/response-shapes.md。 常见错误及其解决方法见 references/troubleshooting.md。 端到端的添加 / 编辑 / 删除操作指南见 references/examples/authoring.md。 初始化 + 根据通话内容刷新操作指南见 references/examples/lifecycle.md。 知识图谱检查指南见 references/examples/graph-queries.md。

初始化

如果已登录（cargo-ai whoami 返回一个工作区），请跳到下一节。

npm install -g @cargo-ai/cli            # no global install? prefix every command with `npx @cargo-ai/cli`
cargo-ai login --email [email protected]  # emailed code, no browser; creates the account on first use
                                        # alternatives: --oauth (browser) · --token <api-token> (CI)
cargo-ai whoami                         # confirm the active workspace before any write

每条命令都会将 JSON 打印到 stdout；失败时会以非零状态码退出，并将错误打印到 stderr（通过管道传递时：{"error": "...", "status": <http>, "body": {"reason": "..."}}，其中 body.reason 是机器可读的原因）。任何会创建 run 或 batch 的命令都是异步的——请传入 --wait-until-finished，或轮询对应的 get 命令。runtime write 和 runtime edit 会提交并推送到工作区的 context 仓库，因此必须先确认 workspace.name。安装完整技能包后，../cargo/references/prerequisites.md 会补充 CLI 版本固定要求、令牌作用域和仅限管理员使用的功能。

先了解 context

编辑任何内容前，先查看 context 仓库中的内容：

cargo-ai context runtime browse                 # list entries at the runtime sandbox root
cargo-ai context graph get                      # full knowledge graph derived from the repo's md/mdx files

快速参考

# Runtime sandbox (checked-out copy of the context repo)
cargo-ai context runtime browse [--path <path>]
cargo-ai context runtime read --path <path> [--start-line <n>] [--end-line <n>]
cargo-ai context runtime write --path <path> --content <content> [--commit-message <message>]
cargo-ai context runtime edit --path <path> --old-string <old> --new-string <new> [--replace-all] [--commit-message <message>]
cargo-ai context runtime execute --command <command> [--args <json>] [--commit-message <message>]

# Knowledge graph
cargo-ai context graph get

运行时沙盒

运行时沙盒是上下文仓库中已检出、可执行的副本。你可以通过它读取和修改上下文文件，并对这些文件运行命令。

请记住以下两项重要行为：

• write 和 edit 会推送到上下文仓库的默认分支。 它们并非仅在本地生效。
• execute 也会推送。 如果命令使受 Git 跟踪的文件被添加、修改、删除或重命名，这些更改会自动提交（提交说明为 context(runtime): execute <command>，也可使用 --commit-message 指定），并推送到默认分支。Git 忽略的路径会跳过。通过 execute 运行的 sed -i 或 rm 操作也会进入 Git。

镜像内容文件以只读方式存放在 .files/ 下。 使用 mirrorToContext: true 保存的内容文件——这是 content file upload、Web 应用上传和 defineFile 的默认设置（参见 cargo-content）——会提交并推送到上下文仓库中的 .files/<folder path>/<name>（提交标题为 content(mirror): upsert <name>、… move …、… remove …；超过 10 MB 的文件会以 JSON 元数据旁文件的形式保存，而不是保存文件字节）。通过 execute 运行的命令（或使用 read/browse）可以访问这些文件，例如：cargo-ai context runtime execute --command ls --args '["-1",".files"]'。通过路径写入的文件（content file put、objects API、workers、writeFile 节点、Agent 写入）默认设置为 mirrorToContext: false，不会存放在那里。你无法从运行时向 .files/ 添加或更改任何内容（deniedPath）——请使用 cargo-ai content file …。任何能够读取上下文仓库的人都可以读取其中的每个镜像文件。

由于写入会立即推送，首次使用 write/edit 前，请确认目标工作区：

cargo-ai whoami   # → workspace.uuid, workspace.name

将工作区名称告知用户并请其确认。如果会话针对特定客户端，请确保 workspace.name 匹配，再开始编写任何内容——此处没有试运行模式。如果 workspace.name 是通用名称或含义不明确（例如“Main”“Test”、某人的姓名或内部代号），不要猜测——请向用户询问公司名称和规范域名（example.com），并在首次写入前确认两者。如果登录时未固定工作区，请重新运行 cargo-ai login --oauth --workspace-uuid <uuid>（非交互式使用时，可改用 --token <workspace-scoped-token>）。

根据销售通话分析得出的编辑应逐项应用并由人工审核，不要批量处理。让 Agent 循环分析大量通话，往往会过度放大最强烈的信号并忽略细微差别——请参阅 references/examples/lifecycle.md 中的通话刷新操作指南。

浏览和读取

# List entries at the root of the runtime sandbox
cargo-ai context runtime browse

# List entries under a subpath (e.g. a domain folder like persona/ or play/)
cargo-ai context runtime browse --path persona

# Read a full file
cargo-ai context runtime read --path persona/vp-sales-mid-market.md

# Read only a line range (1-indexed, inclusive on both ends)
cargo-ai context runtime read --path play/inbound-trial-to-paid.md --start-line 1 --end-line 40

写入新文件

write 会创建（或覆盖）文件，并将提交推送到默认分支。

每个 .md/.mdx 文件都必须以 YAML frontmatter 块开头，并设置 title 和 description。write 不会验证 frontmatter（项目的 defineContext 会验证——参见文件约定）。即使 frontmatter 缺失、为空或格式错误，文件仍会写入并提交；只是它在图谱中的索引效果较差（如果缺少 title，则回退到文件名；节点摘要则回退到首段）。write 也可能因其他原因失败：repositoryNotFound、failedToWrite（包括推送未成功）或 deniedPath（例如写入 .files/ 下的路径）；请参阅 references/response-shapes.md。

cargo-ai context runtime write \
  --path persona/vp-sales-mid-market.md \
  --content "$(cat <<'EOF'
---
title: VP of Sales, mid-market
description: Owns pipeline, quota, and rep productivity at a 200–2,000-person company.
---

## Role
- Title: VP of Sales
- Seniority: Executive
- Function: Revenue
- Reports to: CRO or CEO

## KPIs
- New ARR, win rate, pipeline coverage, rep ramp time

## Pains
- Pipeline gaps, slow ramp, low rep activity, forecasting drift

## Motivations
- Hit the number, build a repeatable motion, get visibility

## Day-to-day
Forecast calls, deal reviews, pipeline reviews, 1:1s with frontline managers.

## Preferred channels
- medium/linkedin-outbound
- medium/exec-warm-intro

## Common objections
- objection/we-already-have-an-ai-sdr

## How we land
Lead with pipeline-coverage math, not features.
EOF
)" \
  --commit-message "Add VP of Sales mid-market persona"

编辑现有文件

edit 会替换一个完全匹配的子字符串。--old-string 在文件中必须恰好出现一次（除非传入 --replace-all）；要删除匹配内容，请传入空的 --new-string。字符串会按字面值处理：普通双引号中的 \n 是反斜杠和字母 n，而不是换行符，因此多行匹配请使用 bash $'...' 引号。

edit 不会验证 frontmatter——即使编辑操作移除或清空了 title/description，也仍会生效；要让节点保持可发现状态，请保留 frontmatter 块。不过，edit 也可能因其他原因失败：stringNotFound / stringNotUnique（--old-string 匹配问题）、fileNotFound、noOp（新字符串与旧字符串相同）、failedToEdit（包括推送未成功），或 deniedPath。

# Replace one specific sentence
cargo-ai context runtime edit \
  --path global/positioning.md \
  --old-string "We help RevOps automate workflows." \
  --new-string "We help RevOps run AI-native GTM motions." \
  --commit-message "Refresh positioning one-liner"

# Delete a line (pass empty --new-string)
cargo-ai context runtime edit \
  --path persona/vp-sales-mid-market.md \
  --old-string $'\n- Outdated stat: 4.2x pipeline\n' \
  --new-string ""

对于较大规模的重构，优先使用 write（覆盖整个文件），而不要连续调用多次 edit。

在沙箱中执行命令

execute 会在沙箱中运行 shell 命令（超时时间为 90 秒）。它适合用于检查结构或运行检查；它留下的已跟踪文件更改会被提交并推送，因此检查命令应保持只读。

# Find every file that cross-references a specific slug
cargo-ai context runtime execute \
  --command grep \
  --args '["-r","-l","persona/vp-sales-mid-market","."]'

# Count entries per domain
cargo-ai context runtime execute --command ls --args '["-1","persona"]'

# Run a one-shot script (no quotes/escaping needed inside --command beyond JSON for args)
cargo-ai context runtime execute --command pwd

--args 是一个由字符串参数组成的 JSON 数组。无参数命令可省略此选项。

上下文仓库结构与约定

Cargo 上下文仓库是一个类型化知识库。规范示例，以及下文所述约定的来源，是 getcargohq/cargo-workspaces；编写新条目之前，请阅读其中各领域的 README.md 和 _template.md 文件。完整的领域参考请见 references/conventions.md。

领域

领域	用途
global/	公司级上下文：使命、声音、定位、叙事、定价
icp/	理想客户画像细分
persona/	买家角色（ICP 内的职位）
jtbd/	待完成任务的框架
alternative/	竞争对手、替代方案、现状
client/	客户档案、案例研究、参考客户
insight/	市场洞察与观察
medium/	渠道手册（电子邮件、LinkedIn、冷电话等）
objection/	异议 + 回复 + 证据
play/	GTM 策略（信号 → 受众 → 渠道 → 流程 → 结果）
proof/	原子化证明要点（指标、引述、案例数据）
signal/	购买信号与意向触发因素

文件约定

• 文件名： kebab-case.md（例如 vp-sales-mid-market.md）。
• Frontmatter： 每个 .md/.mdx 文件都以 YAML frontmatter 开头，并设置 title 和 description。这是强约定，但不强制执行——即使 frontmatter 缺失、为空或格式错误，文件仍会创建并提交；只是索引效果较差。图谱读取 title（回退到文件名）和 summary（回退到 description，再回退到文件首段），因此只有在希望节点摘要不同于 description 时才添加 summary:。请参阅源引用与图谱边。例外情况是项目中声明的上下文（defineContext，见 ../cargo-project/SKILL.md）：在这种情况下，如果 frontmatter 无法解析，或者 references: 条目、[[wikilink]] 或相对 .md 链接与 files 中声明的任何文件都不匹配，project check/plan/deploy 就会失败——即使该文件存在于工作区仓库中，但未在代码中声明也不例外。缺少 title/description 仍可通过检查。
• 交叉引用： 使用 domain/slug 格式，不带 .md 扩展名（例如 persona/vp-sales-mid-market）。要注册为图谱边，引用必须采用以下三种链接形式之一——在普通文本中单独写出 domain/slug（或文件路径）不会创建边。
• 模板： 每个领域都提供一个 _template.md。编写新条目前请先阅读（cargo-ai context runtime read --path persona/_template.md）。_template.* 文件会从图谱中排除——切勿引用它们。

源引用与图边

知识图谱由仓库中所有 .md、.mdx、.yaml 和 .yml 文件构建（任意文件夹；仅排除 .git/）。每个文件都是一个节点，但只有以下三种形式会创建边——其他内容在图谱中不可见：

1. Frontmatter 中的 references: 列表（推荐用于来源引用——让正文保持简洁）：

   ---
   title: AgoraPulse expansion thesis
   description: Why AgoraPulse is ready for a multi-thread expansion play.
   references:
     - outputs/sales-notes/2026-06-05-agorapulse-build-session-1-outcomes.md
   ---
   

2. 正文中的 Markdown 链接——标准的 [label] 后紧跟 (path) 语法，其中目标是文件路径，例如链接到 outputs/sales-notes/2026-06-05-agorapulse-build-session-1-outcomes.md 的锚点。
3. 正文中的 Wiki 链接（扩展名可选）：[[outputs/sales-notes/2026-06-05-agorapulse-build-session-1-outcomes]]。

关键限制：

• 切勿在正文中将来源写成裸路径（例如，Source: 行中仅将 outputs/sales-notes/foo.md 作为文本提及）——系统不会解析它，也不会创建任何边。
• 优先使用相对于根目录的路径（先从仓库根目录解析，再相对于引用文件解析），这样无论文档位于何处，链接都能正常工作。
• Wiki 链接和 frontmatter references: 中的扩展名可选：解析器会按 .md、.mdx、.yaml、.yml 的顺序自动尝试。Markdown 链接只有在目标以 .md、.mdx、.yaml 或 .yml 结尾时才会被视为图边，因此请在链接中保留扩展名。
• 目标必须存在，否则图边将会失效（在图谱 UI 中显示为失效链接）。引用前请使用 runtime browse 验证。
• 对于包含 Source/Evidence 部分的文档，请在 frontmatter references: 中引用文件；如果引用需要配合周围正文，则使用行内 Markdown 链接。完整规则请参阅：references/conventions.md。

工作流：添加新条目

1. 确认目标领域并复制其模板：

   cargo-ai context runtime read --path persona/_template.md
   

2. 在 <domain>/<slug>.md 创建新文件，填写 title、description 和正文各部分。
3. 在适用处添加交叉引用（domain/slug）——合适时保持双向引用。
4. 重新构建知识图谱，验证新条目及其链接：

   cargo-ai context graph get
   

各领域的完整模板和示例请参阅 references/conventions.md 和 references/examples/authoring.md。

工作流：初始化与刷新

要从头搭建新工作区的上下文仓库，或按固定周期刷新现有仓库，请遵循 references/examples/lifecycle.md 中的两阶段生命周期：

1. 初始化（一次性）： 从公开来源填充 global/、persona/、client/、proof/、objection/、signal/，然后针对填充后的仓库启动一个全新的 Agent 会话。对于规定性且可自动化的版本（输入领域 → 输出文件、幂等、包含积分预算），请使用 references/examples/bootstrap-from-domain.md。
2. 刷新（每 2–4 周）： 拉取最近约 3 个月的销售电话转录 → 一次分析一个，并让人在环路中参与 → 应用重复次数阈值，再将任何主张提升为上下文 → 通过生成序列排列组合进行验证 → 比较刷新前后的图谱差异，并淘汰过时条目。

重复次数阈值（某个主张必须在多少次通话中出现，才能纳入上下文）记录在 references/conventions.md 中。

知识图谱

context graph get 会为 context 仓库中的每个 markdown/MDX 文件构建知识图谱（或从缓存加载）。可用于：

• 审查不同领域之间的交叉引用（例如，查找链接到未附带证明的 play 的角色画像）。
• 在编写新条目之前，了解已有内容（避免重复）。
• 为需要工作区上下文类型化结构的下游 Agent 提供支持。

cargo-ai context graph get

响应为 {"graph": {"nodes", "edges", "broken", "computedAt"}}：每个节点包含 id（文件路径，含扩展名）、title、summary 和 cluster（顶层文件夹）；每条边包含 source、target 和 origin（frontmatter、wikilink 或 mdlink）；broken 列出目标不存在的边。可通过管道传给 jq 进行筛选。请参阅 references/examples/graph-queries.md，其中包含可直接运行的查询。

帮助

每个命令都支持 --help：

cargo-ai context --help
cargo-ai context runtime browse --help
cargo-ai context runtime read --help
cargo-ai context runtime write --help
cargo-ai context runtime edit --help
cargo-ai context runtime execute --help
cargo-ai context graph get --help