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 与构建说明。

English

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

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

安装 Agent 接入

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；指定宿主时传仓库根，不再传宿主目录。全局安装不变。自动探测不代表宿主已加载，安装后需刷新宿主。

宿主必须支持发现目标位置。局部入口没有插件命名空间。--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-*），详见插件契约。用户应该从知识意图开始，而不是内部命令：

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

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

飞书读取身份

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

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

用户知识目标
     ↓
单一 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 中。

知识生产生命周期

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

普通对话与全托管对话

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

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

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

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

工作区状态

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 和 Package Templates。

诊断和直接使用 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。参见安装后快速说明和 debug tracing。

文档与开发

• 插件契约
• Workflow Provider 内部说明
• SDK 文档索引
• 知识项目完整示例
• Agent Guide
• Project API

源码、link、打包安装和发布流程参见 DEVELOPMENT.md 以及本包的 DEVELOPMENT.md。

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。已批准页面和其他生产成果保留。