# teaql-agent-kit

**Repository Path**: doublechaintech/teaql-agent-kit

## Basic Information

- **Project Name**: teaql-agent-kit
- **Description**: teaql生态入口，面向AI Native的Harness工程
- **Primary Language**: HTML
- **License**: MIT
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 1
- **Forks**: 0
- **Created**: 2026-07-02
- **Last Updated**: 2026-10-31

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# TeaQL Agent Kit

[Gitee 仓库](https://gitee.com/doublechaintech/teaql-agent-kit) · [English](README.en.md) · [构建应用的 Skill](skills/build-teaql-app/SKILL.md) · [上下文工具](packages/agent-context-kit/README.md)

> 给你正在使用的 Coding Agent 一个任务，让它从业务模型出发，构建并验证 TeaQL 应用。

<table>
  <tr>
    <td align="center"><img src="assets/coding-agents/claude-code.svg" width="48" height="48" alt="Claude Code"><br>Claude Code</td>
    <td align="center"><img src="assets/coding-agents/codex.svg" width="48" height="48" alt="Codex"><br>Codex</td>
    <td align="center"><img src="assets/coding-agents/cursor.svg" width="48" height="48" alt="Cursor"><br>Cursor</td>
    <td align="center"><img src="assets/coding-agents/github-copilot.svg" width="48" height="48" alt="GitHub Copilot"><br>Copilot</td>
    <td align="center"><img src="assets/coding-agents/gemini-cli.svg" width="48" height="48" alt="Gemini CLI"><br>Gemini CLI</td>
    <td align="center"><img src="assets/coding-agents/pi.svg" width="48" height="48" alt="Pi"><br>Pi</td>
  </tr>
  <tr>
    <td align="center"><img src="assets/coding-agents/qoder.svg" width="48" height="48" alt="Qoder"><br>Qoder</td>
    <td align="center"><img src="assets/coding-agents/deepseek-harness.svg" width="48" height="48" alt="DeepSeek Harness"><br>DeepSeek Harness</td>
    <td align="center"><img src="assets/coding-agents/zcode.png" width="48" height="48" alt="ZCode"><br>ZCode</td>
    <td align="center"><img src="assets/coding-agents/trae.svg" width="48" height="48" alt="TRAE"><br>TRAE</td>
    <td align="center"><img src="assets/coding-agents/opencode.svg" width="48" height="48" alt="OpenCode"><br>OpenCode</td>
  </tr>
</table>

TeaQL Agent Kit 将**模型先行的应用开发流程**与**管理 Agent 上下文和工具边界的组件**放在同一个仓库。两部分可以分别使用：

| 组件 | 作用 | 入口 |
| --- | --- | --- |
| **Build TeaQL App Skill** | 建模、评估、生成、实现、验证，并按当前模型获取 Assist 接口说明 | [`skills/build-teaql-app/`](skills/build-teaql-app/SKILL.md) |
| **Agent Context Kit** | 上下文生命周期、受控文件访问、确定性工具反馈和宿主适配器 | [`packages/agent-context-kit/`](packages/agent-context-kit/README.md) |

能读取 Skill 的 Agent 可以遵循 TeaQL 开发流程。文件访问、上下文回收等运行时控制则取决于具体宿主及其启用的适配器；上方列出某个 Agent，不代表它已经启用了全部治理功能。

## 快速开始

在 Coding Agent 中打开一个**应用项目目录**，把下面的任务发到聊天框。将第一行改为本机实际的 Agent Kit 路径，并按需替换业务要求：

```text
请阅读 ~/githome/teaql-agent-kit/skills/build-teaql-app/SKILL.md，并遵循其中的工作流程。

用 Rust 和 SQLite 构建一个包含客户、商品、订单的小型订单管理应用。
先保存完整的 KSML 业务模型，评估并修复模型错误，再生成可运行的应用。
编写并运行 Q 查询、E 表达式的测试和运行烟测，报告实际结果及遗留问题。

最后在 work-complete.md 中写一份有证据的开发报告：
- 引用实际的模型评估、生成、构建、测试及运行结果，说明失败与跳过项；
- 展示本次应用中确实运行过的 Q 查询和 E 表达式；
- 说明业务模型、生成库、Runtime、Assist 与应用代码分别完成了什么；
- 有可比基线才报告 token 或上下文节省量，否则注明“未测量”；
- 区分本次小应用实际证明的结果与对大型项目的预期。
```

Agent 需要有权读取 Skill、修改应用目录并执行开发命令。默认流程可能安装 TeaQL 客户端和语言工具、下载依赖，并向配置的 TeaQL 服务发送模型内容以获取评估、生成和接口说明。处理私有业务需求时，请按组织的数据共享要求配置服务与权限。本地读取 Skill 不会使模型评估和生成自动离线。

本 Gitee 版使用中国区 Generation Service 地址 `https://api.doublechaintech.com/latest/`。启动 Rust Coding Agent 前，在同一终端设置 `TEAQL_ENDPOINT_PREFIX=https://api.doublechaintech.com/latest/`；Java Maven 命令传入 `-Dteaql.endpointPrefix=https://api.doublechaintech.com/latest/`。保存完整模型、核对客户端版本后，在首次评估前确认该地址已生效。其他客户端的配置与检查方式见 [Skill 的中国区提示](skills/build-teaql-app/SKILL.md)。

从 Gitee 获取完整 Agent Kit：

```sh
git clone https://gitee.com/doublechaintech/teaql-agent-kit.git
```

克隆后，将 `teaql-agent-kit/skills/build-teaql-app/SKILL.md` 的本机路径提供给 Coding Agent。Skill 本身不要求安装本仓库的 Node workspace；上下文工具的安装方法见下文。

## 开发流程

```mermaid
flowchart LR
    R[业务需求] --> M[保存 KSML 领域模型]
    M --> E[评估并修复]
    E -->|零错误| G[生成类型化契约]
    G --> A[Assist 与应用代码]
    A --> V[编译、测试与运行证据]
    V -->|诊断反馈| A
```

领域模型定义业务对象、关系和约束；生成库提供领域专属的类型化 API；语言 Runtime 处理共享的执行和持久化能力；应用自有代码承载业务流程、集成与界面。

| 阶段 | Agent 要做的事 | 可检查的结果 |
| --- | --- | --- |
| 建模与评估 | 保存完整 KSML，评估并修复错误 | 模型和评估报告 |
| 生成 | 达到零错误后，仅生成目标目录列出的产物 | 生成库与可编辑应用工作区分离 |
| 实现 | 阅读生成的应用说明和当前对象、操作、字段的 Assist | 聚焦业务代码，查询声明目的和备注，写入声明审计原因 |
| 验证 | 编译、测试、运行并局部修复 | 实际计数、日志、失败与阻塞项 |

模型评估达到零错误时，Agent 报告模型路径及错误、警告数量，并继续后续工作；人工可以并行审阅。如果反馈改变了领域契约，应重新评估并生成。具体命令与生成 API 以当前 Skill、目标目录和 Assist 为准。

## 能得到什么

Robot Task Board 是一个可运行的示例。TeaQL 的 `Q` API 把过滤、字段选择、关联加载、排序、数量限制等组合成可审阅的查询，类型检查能在运行前发现无效的 API 调用：

```rust
let task = Q::tasks()
    .with_id_is(id)
    .comment("Load task for status transition")
    .purpose("Move a task on the board")
    .execute_for_one(&ctx)
    .await?;
```

`E` API 沿类型化路径访问已加载的业务数据，并区分“值不存在”和“字段尚未加载”：

```rust
let name = E::task_status(status)
    .get_name()
    .eval()
    .unwrap_or(raw_str);
```

示例中的实际查询、SQL、审计差异与界面变化见[图文说明](https://teaql.io/blog/robot-task-board-showcase/)。日志记录业务意图和执行结果，有助于调试与复核；新生成项目仍应使用其当前 Assist 确认精确方法名。开发者需要审阅业务规则并验证结果。

## 上下文与工具治理

Skill 说明开发流程；支持它的宿主工具可以进一步控制 Agent 读取、修改和执行的范围。TeaQL 语言 Runtime 则在应用运行时执行已安装的数据操作规则。这些层的启用方式各不相同。

| 能力 | 实现位置与边界 |
| --- | --- |
| 模型先行 | Skill 要求完整模型、语义评估和零错误生成门槛；受信任的 Pi Rust 工具也能对未变化的已评估模型执行生成门槛 |
| 精确接口发现 | 先请求实体与操作的 Assist，再按需请求字段级 Assist；通过 Skill 与配置的读取边界避免搜索生成实现 |
| 上下文生命周期 | 一次性消息、具名阶段块和受信任的丢弃操作；原始会话继续保留 |
| 文件策略 | `.agent-no-read.md`、剪枝遍历、明确的写入根目录与只读路径；由受保护 Pi 或 OpenCode 严格入口执行 |
| 可恢复的错误反馈 | 明确的不可重试错误码、限定范围的拒绝提示和有界结构化诊断 |
| 完成验证 | 受保护 Pi 同时配置 `app_build` 与 `app_test` 时，修改后必须重新完成相应检查 |
| 运行时治理 | 由所选 TeaQL 语言 Runtime 执行身份、查询目的、审计写入及显式授权的能力 |

### 控制生成实现的读取

业务模型、应用指南和可编辑的业务源码保持可读。在生成实现目录中放置 `.agent-no-read.md`；支持该标记的适配器会在读取、搜索和遍历之前检查策略。示意：

```text
project/
  models/
  rust-lib-core/lib/
    .agent-no-read.md
  rust-app-console/
    AGENTS.md
    src/
  context-markers.json
```

标记正文是有界的项目指引，不授予绕过权限。[维护工具与清单](packages/agent-context-kit/docs/context-marker-maintenance.md)可在生成过程替换目录后恢复和检查标记。读取排除与写入许可分别配置；共享[文件策略](packages/agent-context-kit/docs/file-policy.md)默认不允许写入，按需设置 `writeRoots`、`readOnlyPaths`。这些宿主适配器并非操作系统沙箱。

### 让临时信息按时退出

一次性输出使用 `<!--ephemeral-->`，让内容进入一次适用的模型请求，之后在后续请求中由短占位符替代；原始会话仍可复查：

```markdown
<!--ephemeral-->
供下一步实现使用的临时接口说明。
```

阶段规则可以放在具名块中，完成阶段后由可信流程明确丢弃：

```markdown
<!--BLOCK_ID:phase_modeling-->
生成应用代码之前，先评估并修复业务模型。
<!--/BLOCK_ID:phase_modeling-->

<!--DISCARD_BLOCK:phase_modeling-->
```

普通工具输出不能撤销受信任的规则。详见[生命周期协议](packages/agent-context-kit/docs/protocol-v1.md)与 [Pi 适配器](packages/agent-context-kit/docs/pi-adapter.md)。

### 返回可以指导修复的错误

受保护 Pi 将被策略拒绝的读取作为真实工具错误返回，例如 `CONTEXT_ACCESS_DENIED`，并保持 `retryable: false`。二进制文件、超大文件、路径缺失和权限失败也有明确反馈。可选的 [TeaQL Rust 受信任工具](integrations/pi-teaql/README.md)提供 `teaql` 评估、Assist 和受控重新生成，以及 `app_build`、`app_test` 检查。原始编译输出和排除的源码不会直接进入模型上下文。

受保护 Pi 还能检测连续只承诺行动、没有工具调用的停滞对话，在保留会话记录与用户指令的前提下重建请求视图；每个请求最多自动恢复一次。当 `app_build` 和 `app_test` 都已注册时，成功的文件修改会使旧检查失效，Agent 提前停止时宿主会运行缺失的固定检查。用户取消会停止检查；自动验证每个请求最多三轮。退出码为零但实际执行零个测试，不构成测试覆盖证据。详见[旧会话恢复记录](docs/pi-old-session-recovery-verification.md)和[完成验证契约](packages/agent-context-kit/docs/pi-cli-policy.md#completion-verification-after-mutations)。

## 各 Agent 的实际覆盖

以下是 **2026-10-25 的仓库实现快照**。安装生命周期插件不会同时启用文件策略、TeaQL 工具和完成验证；应先选择具体宿主入口。

| 宿主入口 | 当前覆盖范围 |
| --- | --- |
| **受保护 Pi 原生 CLI** | 内联生命周期、标记感知的读／搜／列与受控写入；可选 Rust TeaQL 工具；配置构建和测试工具后可自动补齐完成检查 |
| **OpenCode V2 严格插件** | 可选的可信生命周期文件、标记感知文件访问、明确写入根目录和受控修改；可配置固定诊断，不包含 Pi 的 TeaQL 工具模块与完成守卫 |
| **普通 Pi / OpenCode 生命周期插件** | 具名块、可信丢弃与一次性内容；ReadGuard 需单独配置，共享写入策略未集成 |
| **Pi 专用 SDK Harness** | 标记感知的只读边界与可选固定检查；默认未组合生命周期适配器 |
| **Cline / Kilo / MiMo / DeepSeek / Gemini** | 生命周期与读取控制因宿主而异，不能推断全部具备严格文件边界 |
| **Hermes / Kimi / Qwen / Kiro** | 当前请求的块或上下文与配置好的 ReadGuard；不声明完整的一次性历史改写或共享写入策略 |
| **Copilot CLI / Crush** | 配置好的 ReadGuard；不声明生命周期历史改写 |
| **Codex / Claude Code / Cursor 等 Skill 宿主** | 可使用 Skill 指引；这里不声明 Context Kit 已在这些宿主上执行运行时强制控制 |

ReadGuard 的路径／工具阻断与标记策略的遍历、自动上下文检查是不同的边界。完整功能矩阵见[激活指南](docs/agent-feature-activation.md)和[适配器兼容说明](packages/agent-context-kit/docs/compatibility.md)。

受保护 Pi 需要由宿主将原生 bootstrap 接到普通 `pi` 启动入口，并配置所需受信任工具；安装或更新后请开启新会话。OpenCode 严格模式需要独立的 V2 配置、写入根目录和上下文路径；V1 不支持严格模式。两种受保护入口都限制任意 Shell、未经防护的 MCP／委托和自动外部资源加载。配置说明分别见 [Pi 文档](packages/agent-context-kit/docs/pi-cli-policy.md)与 [OpenCode 文档](packages/agent-context-kit/docs/opencode-context-policy.md)。

## 验证记录与适用范围

仓库记录了 **154 项通过**：118 项包单元测试、21 项集成测试、8 项根目录契约测试和 7 项 Python 测试，覆盖解析、文件策略、生命周期、打包、诊断及完成检查。部分本地 Pi 集成测试使用可重复的模拟 Provider。具体真实模型运行记录与范围分别见 [Pi 旧会话恢复](docs/pi-old-session-recovery-verification.md)、[t003 业务修复](docs/t003-business-repair-verification.md)和 [OpenCode 严格模式 t003](docs/opencode-t003-verification.md)。t003 业务修复的测试命令退出码为零，但实际运行 **0 个测试用例**，不能视为业务测试覆盖。

设备适配和模型评估记录不单独证明完整应用正确性；没有可比基线时，也不能报告实际 token／上下文节省率。

在仓库根目录重跑检查：

```sh
npm ci
npm run check
npm pack --workspace @teaql/agent-context-kit
```

## 安装与目录

| 路径 | 内容 |
| --- | --- |
| [`skills/build-teaql-app/`](skills/build-teaql-app/) | 模型先行 Skill、语法示例、工具链说明、局部修复和完成证据要求 |
| [`packages/agent-context-kit/`](packages/agent-context-kit/) | 可独立打包的 `@teaql/agent-context-kit`、宿主适配器与标记维护工具 |
| [`integrations/pi-teaql/`](integrations/pi-teaql/) | 受保护 Pi 的可选 Rust TeaQL 工具 |
| [`tools/teaql_workspace.py`](tools/teaql_workspace.py) | 显式选择并验证 workspace 或 release Runtime 来源 |
| [`docs/`](docs/) | 功能激活说明与集成验证记录 |

根目录是私有 Node workspace，不能作为 npm 包发布。开发上下文工具需要 Node.js 22.19+，并使用锁定的 Pi 1.4.0、OpenCode 插件 SDK 2.1.4 开发依赖；安装或发布时应明确选择子包。详见[仓库开发说明](docs/context-runtime.md)和[宿主安装说明](packages/agent-context-kit/docs/installation.md)。

生成工作区默认声明已发布 TeaQL 依赖。应用可通过 `teaql-workspace.yaml` 选择带有精确仓库提交与工作树状态证据的 `workspace` 模式，或选择基于包版本、无本地覆盖的 `release` 模式。参考 [workspace](examples/teaql-workspace.workspace.yaml) 与 [release](examples/teaql-workspace.release.yaml) 配置：

```sh
./tools/teaql_workspace.py apply --config teaql-workspace.yaml --workspace /path/to/application
./tools/teaql_workspace.py verify --config teaql-workspace.yaml
```

覆盖配置属于应用工作区；生成器不会写入维护者本机路径。`apply` 会记录 `.teaql/runtime-source-evidence.json`。

## 语言、示例与生成服务

TeaQL 应用生成覆盖 **Java、Rust、Go、Swift、Python、C#/.NET、TypeScript** 七种语言家族。Kotlin/JVM 应用可通过生成的 Java 库和 Java Runtime 接入，但不算第八种生成目标或 Runtime。Swift 当前提供本地优先的 SQLite Runtime 与 TFP 客户端，没有独立可编辑应用目标或 TFP 服务端。C++、Dart、Ruby 等未列出的语言不在当前支持范围内。

七语言的生成能力与受保护 Pi 工具的 Rust 工作流子集应分别理解。具体 API 以服务当前目标目录和模型感知 Assist 为准。[历史 Runtime／数据库矩阵](docs/runtime-feature-snapshot.md)记录的是 **2026-08-12** 的证据，本次 README 调整并未重新验证该矩阵。

可运行示例按语言分别维护工具链和发布周期，包括 Android Robot Task Board、Compose Desktop 自动售货机、Java／Rust World Cup CLI，以及 Rust Linux `/proc` 查询示例。示例提供代码与运行证据；完整 Agent 执行记录还应包含原始模型、评估修复、Assist、策略检查、编译、测试与运行结果。

[TeaQL Generation Service 中国区在线演示](https://api.doublechaintech.com/latest/)提供模型评估和修复提示、七语言类型化领域库、可编辑应用工作区、按实体和字段逐级获取的查询 Assist、对象创建／更新／删除／表达式指引，以及当前领域的 Runtime／工具说明。查询 Assist 先请求 `language-assist-query/entity`，需要具体字段时再请求 `language-assist-query/entity.field`；路径使用规范 KSML 名称。

希望了解开源 Rust 生成实现的开发者可阅读 [teaql-forge-rs 介绍](https://teaql.io/blog/teaql-forge-rs-open-source/)。它是较小的开源实现，不声明与 TeaQL Generation Service 完全等价。

## 许可证

Skill 与仓库根目录材料使用 [MIT License](LICENSE)。独立的 `packages/agent-context-kit/` 包使用其目录中的 [Apache-2.0 License](packages/agent-context-kit/LICENSE)；随附素材保留各自的许可证。