CarryCtx 核心技能是做什么的？

CarryCtx 为 AI 编程代理提供一流的项目状态和上下文连续性。它使代理能够管理任务、跟踪粒度进度、创建检查点快照、维护 AST 代码依赖图、运行 stdio MCP 服务器、应用工作流预设，并在会话重启和 Git 工作树之间无缝保留上下文。

何时应用

在以下场景使用 CarryCtx 命令：

开始新任务或会话时：注册代理身份，启动会话，恢复上下文（carryctx resume）。
管理项目任务时：创建、认领、开始、完成、阻塞或取消任务（carryctx task ...）。
跟踪粒度进度时：记录结构化的 todo、block、risk 和 note 项。
保存状态 / 创建检查点时：在结束会话或切换焦点前，捕获当前工作进度、git 状态和剩余工作。
代码图探索时：扫描 AST 模块依赖（carryctx graph scan）并导出 Mermaid/DOT/ASCII 图表（carryctx graph export）。
AI 代理工具集成（MCP）：通过模型上下文协议 stdio 服务器（carryctx mcp）向 Cursor / Windsurf / AGY 暴露项目上下文。
标准化工作流（预设）：列出、查看和应用项目工作流蓝图、编码规则和代理角色（carryctx preset ...）。
并行任务工作时：在专用的 Git 工作树中创建和隔离任务（carryctx worktree ...）。
诊断健康问题时：运行 carryctx doctor 以发现孤立任务、缺失钩子和数据库问题。
清理旧数据时：使用 carryctx project prune 清理已完成任务并保持数据库轻量。
代理分析时：使用 carryctx stats 审计代理会话时长、任务指标，并导出 Markdown/CSV 报告。
按内容查找先前工作时：使用 carryctx search "<query>" 按关键字查找任务、进度项、检查点或决策，无需手写 SQL 或搜索 git 提交信息。

前置条件

安装 CarryCtx CLI（cargo install carryctx 或使用预构建二进制文件）。
在项目仓库中初始化 CarryCtx：carryctx init。

快速参考

操作	命令	用途
代理设置	`carryctx agent register --name "$(whoami)" --provider "claude-code"`	注册代理身份
当前代理	`carryctx agent current`	显示当前激活的代理身份
启动会话	`carryctx session start`	开始被跟踪的工作会话
恢复上下文	`carryctx resume`	获取当前任务、进度及下一步行动
创建任务	`carryctx task create --title "..." [--depends-on CTX-0001]`	定义新任务
认领任务	`carryctx task claim CTX-0001`	将任务分配给当前代理
编辑任务	`carryctx task edit CTX-0001 [--title ...] [--priority ...] [--description ...]`	更新任务标题、优先级或描述
开始任务	`carryctx task start CTX-0001`	标记任务为进行中
跟踪进度	`carryctx progress <todo	block
检查点	`carryctx checkpoint --done "..." --remaining "..."`	保存语义丰富的状态快照
扫描代码图	`carryctx graph scan`	将 AST 依赖提取到 SQLite 图中
导出图	`carryctx graph export --type <mermaid	dot
MCP Stdio 服务器	`carryctx mcp`	启动带有6个代理工具的 MCP stdio 服务器
应用预设	`carryctx preset apply <preset_name>`	注入工作流标准操作程序、规则或角色
工作树	`carryctx worktree create CTX-0001`	为任务创建隔离的 git 工作树
结束会话	`carryctx session end`	安全结束会话并创建检查点
诊断工具	`carryctx doctor`	诊断项目健康状态
安装钩子	`carryctx hooks install`	在每次 git 提交时自动创建检查点
清理数据	`carryctx project prune --older-than 30`	清理旧的已完成任务
代理统计	`carryctx stats [--markdown] [--output file.csv]`	查看指标并导出性能报告
决策记录	`carryctx decision add --title "..." --task CTX-0001`	记录架构决策
交接工作	`carryctx handoff create --target <agent> --task CTX-0001`	在代理之间转移工作
暂停会话	`carryctx session pause`	暂停激活的会话计时器
恢复会话	`carryctx session resume`	恢复已暂停的会话
搜索	`carryctx search "" [--type task	progress

输出行为（0.5.2+）

文本输出（默认的 --format text）设计紧凑：实体命令每行打印一条简短记录（Task created: CTX-0321，agent current 仅打印名称，列表显示 display_id、状态和裁剪后的标题/摘要），以保持代理上下文占用较小。当需要完整记录时：

--verbose（全局标志）或 .carryctx/config.toml 中的 [output] verbose = true 可恢复完整的格式良好的记录。
--fields display_id,status,summary（全局标志）或每个命令的 [output.fields] 表可将记录修剪为文本和 JSON 中的允许列表。
--format json 始终返回完整信封。

JSON 输出不变，仍是机器契约：每次成功都在标准输出上输出单个信封，每次错误都在标准错误上输出单个信封。

标准代理工作流

1. 会话初始化与上下文恢复

在交互开始或代理重启后：

# 注册并设置身份（如果尚未配置）
carryctx agent current || carryctx agent register --name "claude" --provider "claude-code"

# 启动会话并加载当前上下文
carryctx session start
carryctx resume

暂停和恢复会话：

carryctx session pause    # 暂停激活的会话（计时器停止）
carryctx session resume   # 恢复已暂停的会话
carryctx session end      # 结束会话并可选创建检查点
carryctx session abandon  # 结束会话但不创建检查点

2. 代码依赖分析（图子系统）

在修改代码或重构模块之前：

# 1. 扫描代码库 AST 依赖
carryctx graph scan

# 2. 导出以特定模块为中心的子图
carryctx graph export --type mermaid --focus "src/application/stats.rs" --depth 2

# 3. 导出模块级紧凑 ASCII 架构概览
carryctx graph export --type ascii --compact

3. 工作流预设与规则注入

注入标准操作程序或编码指南：

# 列出可用的工作流预设
carryctx preset list

# 为当前项目应用标准的 bug 修复工作流预设
carryctx preset apply workflows/bugfix

4. 任务生命周期

# 列出待办任务
carryctx task list --status ready

# 认领并开始任务
carryctx task claim CTX-0001
carryctx task start CTX-0001

# 验证后标记任务完成
carryctx task complete CTX-0001

5. 粒度进度跟踪

随着工作进行，记录结构化的进度项：

carryctx progress todo "为认证中间件编写单元测试"
carryctx progress todo "实现 JWT 令牌验证"
carryctx progress block "等待 API 端点规范确认"
carryctx progress risk "上游依赖的破坏性更改"
carryctx progress note "使用 LRU 缓存优化令牌查找"
# 将待办项标记为已完成：
carryctx progress complete PX-0001

6. 创建检查点

在结束会话、切换任务或交接工作前保存状态：

carryctx checkpoint \
  --done "完成后端认证端点" \
  --remaining "前端登录表单集成" \
  --blocker "无"

7. 工作树并行

同时处理独立任务时：

carryctx worktree create CTX-0002
# 切换到与 CTX-0002 链接的隔离工作树目录

7a. 记录决策与交接

捕获架构决策并在代理之间交接工作：

# 记录与任务关联的架构决策（ADR）
carryctx decision add --title "使用 SQLite 作为存储" --task CTX-0001

# 列出或搜索决策
carryctx decision list
carryctx decision search --keyword SQLite

# 将决策标记为被新决策取代
carryctx decision supersede DEC-0001 --by DEC-0002

# 创建交接以将工作转移给另一个代理
carryctx handoff create --target <agent-ulid> --summary "实现 API" --task CTX-0001

# 接受、拒绝或关闭交接
carryctx handoff accept HO-0001
carryctx handoff reject HO-0001 --reason "不属于我的领域"
carryctx handoff close HO-0001

7b. 全文本搜索项目历史

按内容查找先前的工作，无需记住哪个分支或任务涉及了它。搜索任务标题/描述、进度项、检查点注释和决策，全部按相关性排序：

# 搜索所有内容
carryctx search "markdown worker protocol"

# 限定到单一实体类型
carryctx search "retry backoff" --type checkpoint

# 通过拥有任务的状态或拥有者代理缩小范围
carryctx search "auth" --status in_progress
carryctx search "auth" --owner claude-code

每个命中结果都包含拥有任务的显示 ID、状态，以及（如果已知）处理它的分支——在开始相关工作前使用此功能以避免重复解决已解决的问题，并在交接前使用它将接收代理指向解释先前选择的准确检查点或决策。

8. 结束会话与报告

# 结束工作会话
carryctx session end

# 为 PR 描述或文档导出项目统计报告
carryctx stats --markdown --output /tmp/project_stats.md

9. 模型上下文协议（MCP）集成

将 CarryCtx 直接集成到 Cursor / Windsurf / AGY：

{
  "mcpServers": {
    "carryctx": {
      "command": "carryctx",
      "args": ["mcp"]
    }
  }
}

暴露的 MCP 工具：

carryctx_graph_explorer：查询、扫描和导出项目上下文图
carryctx_context_manager：管理持久上下文、检查点和状态快照
carryctx_task_manager：管理项目任务、依赖关系和优先级
carryctx_progress_tracker：管理任务进度、注释和阻塞项
carryctx_decision_logger：记录和搜索架构决策记录
carryctx_project_admin：管理项目数据库、统计信息、冷存储归档和配置

10. 调试与故障排除

启用结构化调试日志以诊断问题：

# 显示 CarryCtx 操作的调试日志
RUST_LOG=carryctx=debug carryctx task list          # 在命令结果前查看调试输出

# 仅显示错误
RUST_LOG=error carryctx status

# 运行诊断
carryctx doctor             # 检查项目健康状态
carryctx doctor --json      # 机器可读的诊断输出

面向编程代理的最佳实践

始终在启动时运行 carryctx resume：立即将代理重新定位到当前任务和进度。
在大规模重构前扫描代码图：carryctx graph scan 可防止破坏上游依赖。
明确认领任务：当多个代理在同一仓库上工作时，防止重复执行。
使用结构化进度项：在执行步骤期间保持 todo、done 和 block 的更新。
停止前创建检查点：在让出控制权或完成复杂的多步骤工作之前始终创建检查点。
首次使用或升级后运行 carryctx doctor：在运行时错误发生前发现设置差距。

CarryCtx 核心技能