teaql-agent-kit

环境要求

• Node.js 环境（npx，用于安装社区 Skills CLI）
• Python 3 环境（用于执行 ./tools/teaql_workspace.py 脚本）
• 支持 Skills 的编码代理（用于调用 $build-teaql-app 工作流）
• 本仓库源码（tools/ 与 examples/ 目录需在本地可用）

安装与启动步骤

1. 1获取项目仓库

   克隆 teaql-agent-kit 仓库到本地，tools/ 下的工作区脚本和 examples/ 下的配置样例都在仓库内。

   git clone https://github.com/teaql/teaql-agent-kit.git
   cd teaql-agent-kit

   复制

2. 2安装 Agent Skill

   用社区 Skills CLI 安装完整“模型到应用”工作流技能 build-teaql-app，装好后即可在编码代理中使用。

   npx skills add teaql/teaql-agent-kit --skill build-teaql-app

   复制

3. 3在代理中调用技能

   向编码代理发出提示，先用 $build-teaql-app 起草并保存完整 KSML 模型，再评估修复、生成可运行应用。

   Use $build-teaql-app to first draft and save a complete KSML model, then
   evaluate and repair it before generating a runnable TeaQL application: ...

   复制

4. 4准备工作区配置

   从 examples 里的样例复制出 teaql-workspace.yaml，该文件使用 JSON 兼容 YAML，验证器无需第三方依赖。workspace 版用于改运行时，release 版用于已发布包回归。

   cp examples/teaql-workspace.release.yaml teaql-workspace.yaml

   复制

5. 5应用运行时源

   apply 会解析配置中选定的运行时仓库（workspace 模式记录精确 commit 与 dirty 状态），并在目标应用工作区写入证据文件。

   ./tools/teaql_workspace.py apply 
     --config teaql-workspace.yaml 
     --workspace /path/to/generated-application

   复制

6. 6校验运行时源

   verify 按配置校验所选运行时仓库，应在执行 Maven/Cargo/Go/npm 等原生包管理器命令之前完成。

   ./tools/teaql_workspace.py verify --config teaql-workspace.yaml

   复制

关键配置

如何确认成功

执行 verify 命令无报错即通过；apply 后在应用工作区可见 .teaql/runtime-source-evidence.json 证据文件。

常见问题

注意事项

• 本仓库是编排/治理框架，本身不是可直接运行的业务应用，端到端运行效果需参考 Java/Rust 应用示例仓库。
• 生成的应用清单只声明已发布的 TeaQL 依赖，不会包含维护者本地文件系统路径。
• 原生包管理器 override（Maven、Cargo、Go、npm、Swift、.NET、Python editable 等）由工作区自行维护，生成器不会创建或猜测。
• 运行时治理只让应用动作具备上下文、边界、可观测与可审计，并不替你选择正确的业务策略。