SuperAPI AI 工具集
合作ENAI 行业资讯收藏
Skill 广场levelup-trace

levelup-trace

智能体与模型

查看项目

更新于 10-16 06:57

技能介绍

用途

levelup-trace 用于从当前智能体会话生成一份会话执行轨迹（session execution trace）。它记录的是智能体在此次对话中实际做了什么，而不是依据 spec-kit 制品。轨迹会捕获用户的请求、智能体的处理方式、关键决策、文件变更以及可复用模式。

其目的包括：记录会话期间发生的事情以便复用和学习；捕获决策模式与问题解决方式；提供证据链（提交、变更文件、工具使用）；生成可供 levelup-specify 消费以进行 CDR 提取的轨迹。

输出文件：.adlc/drafts/trace.md

与 spec-kit 的 spec.trace 的关键区别：spec.trace 读取 spec-kit 制品（spec.md、plan.md、tasks_meta.json）来生成轨迹；而 levelup-trace（本技能）读取当前会话生成轨迹，不依赖 spec-kit。

何时使用

  • 完成工作后：捕获智能体所做的工作以便复用
  • 在运行 /levelup-specify 之前：生成轨迹用于 CDR 提取
  • 会话文档：保留智能体会话记录以供学习
  • 模式捕获：从刚完成的工作中识别可复用模式

何时不使用

  • 工作完成之前：应在实现完成后运行
  • 棕地发现：使用 /levelup-init 扫描现有代码
  • CDR 提取：在运行本技能后使用 /levelup-specify
  • CDR 审查：使用 /levelup-clarify 审查提议的 CDR

使用方式

用户输入 $ARGUMENTS 会被考虑（若非空）。示例："focus on error handling" 强调错误处理模式；"document the testing approach" 聚焦测试决策；空输入则从整个会话生成全面轨迹。

角色定位为 Session Recorder（会话记录者），负责审查当前对话以识别关键动作与决策、收集具体证据（文件变更、提交、工具使用）、生成结构化轨迹文档、识别可复用模式。

执行流程分为六个阶段：

  • 阶段 0 环境设置：从技能基础目录运行 scripts/bash/setup-levelup-trace.sh，解析 JSON 输出中的路径。若脚本不可用或失败，则手动解析：REPO_ROOT（从 cwd 向上查找含 .adlc/ 的目录，或使用 git rev-parse --show-toplevel，或使用 pwd）；TEAM_AI_DIRECTIVE（检查环境变量，再查 REPO_ROOT/.adlc/init-options.json 的 team_ai_directive 字段，最后回退到 REPO_ROOT/team-ai-directives）；CDR_DRAFTS_DIR 为 REPO_ROOT/.adlc/drafts/cdr；TRACE_FILE 为 REPO_ROOT/.adlc/drafts/trace.md。无前置条件，任何会话都可被追踪。
  • 阶段 1 会话审查：识别用户要求（原始请求、澄清、约束）、智能体所做（主要动作、策略、关键决策及原因、遇到的挑战及解决方式）、结果（实现或变更内容、测试是否通过、构建是否成功、执行的验证）。
  • 阶段 2 证据收集：从仓库收集具体证据，包括 git diff --stat、git log --oneline -10、git status --short，以及读取最重要的变更文件。若非 git 仓库，则手动列出会话期间创建/修改的文件。对每条证据记录文件路径、创建/变更内容、其重要性。
  • 阶段 3 生成轨迹：将轨迹写入 {TRACE_FILE}，结构包含标题（生成日期、分支）、Summary（Problem、Key Decisions、Final Solution）、第 1 节 Session Overview、第 2 节 Decision Patterns、第 3 节 Implementation Evidence、第 4 节 Reusable Patterns、第 5 节 Evidence Links。若用户提供输入，则在各节中强调该方面。
  • 阶段 4 验证轨迹：检查完整性——Summary 三部分齐全；第 1-5 节每节至少 3 行内容；证据链接至少引用 1 个提交或文件路径；至少识别 1 个可复用模式。报告覆盖率、证据链接数、可复用模式数及警告。
  • 阶段 5 总结：输出会话描述、轨迹路径、覆盖率、变更文件数、可复用模式数，并交接给 /levelup-specify，交接上下文为 JSON：{"source": "session", "command": "trace", "trace_file": ".adlc/drafts/trace.md", "next": "specify"}。

关键规则

  • 捕获实际发生的事：轨迹记录当前会话，而非规格说明中应发生的事；一切基于具体证据（文件变更、提交、对话）；不虚构或推测未做的事。
  • 证据优先于主张：每个决策都应引用具体文件、提交或对话要点；"看起来是个好模式" 不足以作为依据。
  • 会话优先而非制品优先：轨迹从会话生成，不依赖 spec.md、plan.md、tasks.md 或 tasks_meta.json；适用于任何智能体、任何项目、任何工作流。
  • 轨迹是输入而非输出：轨迹由 /levelup-specify 消费以提取 CDR；轨迹本身不是 CDR，而是原材料；CDR 由 /levelup-specify 提取、由 /levelup-clarify 审查、由 /levelup-publish 发布。

工作流衔接

运行 /levelup-trace 后，必须运行 /levelup-specify 从轨迹中提取 CDR。完整 CDR 生命周期为：智能体会话（工作完成）→ /levelup-trace → 生成轨迹写入 .adlc/drafts/trace.md → 运行 /levelup-specify 从轨迹与会话证据提取 CDR → 运行 /levelup-clarify 审查并接受/拒绝 CDR → 运行 /levelup-publish 将接受的 CDR 编译为 team-ai-directives PR → 运行 /team-repair 在合并后重新索引并验证知识库。

验证

轨迹写入 .adlc/drafts/trace.md；5 个节均存在且有内容；证据链接引用具体文件/提交；至少识别 1 个可复用模式；轨迹可供 /levelup-specify 消费。

配置

  • TEAM_AI_DIRECTIVE：team-ai-directives 知识库路径（覆盖 .adlc/init-options.json）
  • .adlc/init-options.json：项目级配置文件，含 team_ai_directive 字段
  • 默认回退：项目根目录下的 team-ai-directives/

12-Factor 对齐

Factor IX（可追溯性）——捕获会话执行以供复用和学习。

上下文：$ARGUMENTS