cxas-agent-foundry

Agent Foundry

GECX 对话 Agent 的端到端生命周期：构建、测试、调试、迭代。

步骤跟踪 — 必须执行（阶段 0，阻塞）

在开展任何工作之前——包括运行设置、提问或搭建文件——都必须根据相关子技能的检查清单（逐字照搬）初始化 <project>/todo.md。 检查清单是必须遵守的约定，而非建议。如果当前任务没有 todo.md，请拒绝继续，并先创建该文件。

长时间调试或构建时，人们常会在压力下跳过验证步骤（例如，未运行 lint 就推送、未编写 TDD 就搭建文件，或实际上并未推送就声称“已部署”）。检查清单正是为此而设。当你本能地想跳过某一步时，正是检查清单发挥作用的时刻——此时必须查阅它，而不是绕过它。

快速参考

# Lint: dispatch agents/lint-fixer.md sub-agent — DO NOT run `cxas lint` on the main thread.
# Lint output is verbose; keep it inside the sub-agent context.

# Push local files to platform (only after lint-fixer returns status: clean)
cxas push --app-dir <project>/cxas_app/<AppName> \
  --to projects/<project_id>/locations/<location>/apps/<app_id> \
  --project-id <project_id> --location <location>

# Pull platform state to local (use --version-id to export an immutable version snapshot instead of live draft)
cxas pull projects/<project_id>/locations/<location>/apps/<app_id> \
  --project-id <project_id> --location <location> --target-dir <project>/cxas_app/ \
  [--version-id <version_id_or_name>]

# Run evals + triage + report (single command)
python .agents/skills/cxas-agent-foundry/scripts/run-and-report.py --message "what changed" --runs 5

# Generate dynamic interactive HTML dashboard with Gemini LLM failure clustering and parameter filters
python .agents/skills/cxas-agent-foundry/scripts/generate_interactive_report.py --input <path_to_sim_results.json> --output <path_to_report.html>

# Inspect app architecture
python .agents/skills/cxas-agent-foundry/scripts/inspect-app.py

# Triage failures
python .agents/skills/cxas-agent-foundry/scripts/triage-results.py --last 3

# Run all 6 build-verification gates against the deployed app
python .agents/skills/cxas-agent-foundry/scripts/gate-check.py

# Tune scoring thresholds (similarity, hallucination, extra-tools)
python .agents/skills/cxas-agent-foundry/scripts/app-thresholds.py show

# Sync callback Python code into evals/callback_tests/agents/ + create test.py symlinks.
# Required for tests to be discoverable by test_all_callbacks_in_app_dir.
python .agents/skills/cxas-agent-foundry/scripts/sync-callbacks.py                  # post-push: pull from platform
python .agents/skills/cxas-agent-foundry/scripts/sync-callbacks.py --from-local <app_dir>  # pre-push: copy from local app dir

# Snapshot app version (create immutable platform backup)
cxas versions create --app-name projects/<project_id>/locations/<location>/apps/<app_id> \
  --display-name "v1.0.0-snapshot" --description "Pre-refactor baseline"

# List and compare app versions
cxas versions list --app-name projects/<project_id>/locations/<location>/apps/<app_id>
cxas versions compare --app-name projects/<project_id>/locations/<location>/apps/<app_id> \
  --source <version_id_1> --target <version_id_2> --web

# Cold-start setup (first-time only — venv + project bootstrap)
.agents/skills/cxas-agent-foundry/scripts/setup.sh
python .agents/skills/cxas-agent-foundry/scripts/setup-project.py

消歧说明：gate-check.py 和 inspect-app.py 都可以用于“展示架构”，但如果用户即将推送、已经完成构建，或想进行验证检查，应使用 gate-check.py。inspect-app.py 用于快速查看“这里有什么”，不包含验证关卡。拿不准时，使用 gate-check.py。

子 Agent

对于可能耗费主线程上下文的繁重诊断或分析工作，请通过 Agent 工具派遣以下某个子 Agent。将相关 .md 文件的内容作为提示词传入，然后添加该文件列出的输入。

子 Agent	推理强度	使用时机
agents/triage-failure.md	高	诊断一个失败的评测。按类别优先级，并行分派任务排查排名前 5 的失败。首批结果返回后，再继续处理更多失败。
agents/tdd-writer.md	高	根据现有 Agent 逆向工程 TDD，或根据 PRD 起草 TDD。返回 TDD 和待解决问题交接内容；主线程与用户进行展示／询问／迭代循环（子 Agent 无法提问）。
agents/scaffolder.md	中	根据已批准的 TDD 批量生成所有 Agent 代码（Agent JSON、instruction.txt、tool python_code、callbacks、app.json）。一次派遣即可替代主线程编写 30–60 个文件。
agents/coverage-analyst.md	中	根据 Agent 的架构生成完整的评测覆盖率报告。
agents/eval-writer.md	中	为一种完整的评测类型生成评测（所有 golden、所有 sim 等）——自行读取 TDD 的 Coverage Map。每次构建最多派遣 4 次。
agents/lint-fixer.md	低（机械性）	运行 cxas lint，以机械方式修复所有错误和确定性警告，直至检查通过。绝不要在主线程运行 lint。

运行评测时没有可用的子 Agent。使用 scripts/run-and-report.py --json-summary <path> > /dev/null 2>&1 并读取摘要文件——参见 references/debug.md → “快速入门”。这项工作是确定性的，因此由脚本负责执行。

推理强度是给运行时的提示：高强度子 Agent 可从更多思考预算／更强大的模型中获益；低强度子 Agent 按既定步骤执行，无需这些资源。每个子 Agent 文件顶部都会重复此提示，并附上一行理由。

环境就绪检查（路由前执行）

在路由到任何子技能之前，按以下顺序检查这些信号：

1. 虚拟环境是否存在？——检查 .venv/ 目录是否存在
2. 配置是否存在？——检查 .active-project 文件是否存在，以及其中引用的 <project>/gecx-config.json 是否存在
3. 之前是否构建过？——检查是否有任何 <project>/cxas_app/ 目录包含内容

信号	操作
没有 .venv/ 或没有配置	需要首次设置。 在进行任何其他操作之前，加载 references/setup.md。
gecx-config.json 存在，但 cxas_app/ 没有内容	回访用户，新项目。按常规路由。
全部存在	回访用户。按常规路由。

检测意图并路由

理解用户的需求并加载相应的子技能：

用户说……	阶段	加载
“根据这份 PRD 为我构建一个 Agent”	构建	references/build.md
“创建一个新的 cxas 应用”“创建一个新 Agent”“设置一个 Agent”“我想构建一个 Agent”	构建	references/build.md
“为我的 Agent 创建评估”	构建	references/build.md
“生成工具测试”“创建回调测试”	构建	references/build.md
“更新评估——需求变了”	构建	references/build.md
“更新 TDD”	构建	references/build.md
“运行评估”“推送评估”“检查结果”	运行	references/run.md
“运行工具测试”“测试回调”	运行	references/run.md
“生成报告”	运行	references/run.md
“生成交互式报告”“故障聚类仪表板”	运行	references/generating-reports.md → “交互式诊断仪表板”
“为什么这项评估失败了”“达到 90%”	调试	references/debug.md
“修复失败的评估”“调试 Agent”	调试	references/debug.md
“工具测试失败了”“回调测试坏了”	调试	references/debug.md
“对应用版本做快照”“创建版本”“比较版本”“列出版本”	管理	references/api-reference.md → “版本管理”
“编辑 Agent 的指令”“调整身份验证工具”“修复问候语”“更新此回调”	构建（编辑周期）	references/build.md → “编辑现有 Agent”

任何暗示创建、构建或设置 Agent／应用的说法，都应路由到 references/build.md——即使听起来只是“创建应用外壳”。 “创建一个新的 cxas 应用”并非跳过流程直接搭建脚手架；它会触发完整的构建流程（todo.md → 访谈／PRD → TDD + 审批 → 搭建脚手架 → lint → 评估 → 推送）。如果用户说的是“创建”而不是“构建”，就跳过访谈／TDD，这是路由错误。

编辑现有 Agent（调整指令、更改工具、修复回调）应路由到 build.md 的“编辑现有 Agent”部分——标准的拉取 → 编辑 → lint → 推送 → 运行评估周期。不要跳过 lint 或之后的评估运行——静默回归会让通过率从 90% 降到 70%。

如果意图不明确，请询问：“您是想构建／创建评估、运行评估，还是调试失败项？”

开始之前

检查记忆中是否有项目专属背景信息（应用 ID、变量处理规则、音频评分变通方法）。如果没有，请询问用户。