From e103abefb866528d2d555933f72a2f4de0135d94 Mon Sep 17 00:00:00 2001 From: qiansc Date: Tue, 13 Oct 2026 03:18:17 +0800 Subject: [PATCH] chore(v0.3.1): raise example compatibility and link the documentation site Raise the scaffold, template and example compatibility range to ^0.3.0 and document the 0.3.0 Resource protocol migration. The README, contributing, support and development guides now link to the Agent Graph documentation on context4ai.org, describe the ecosystem and list the publishing steps. Co-authored-by: Cursor --- CHANGELOG.md | 5 +++ CONTRIBUTING.md | 2 + DEVELOPMENT.md | 11 ++++- README.md | 41 ++++++++++++++++--- README.zh-CN.md | 41 ++++++++++++++++--- SUPPORT.md | 2 +- docs/en/migration.md | 12 ++++++ docs/en/specification.md | 6 +-- docs/zh-CN/migration.md | 12 ++++++ docs/zh-CN/specification.md | 6 +-- examples/choice-routing/provider.yaml | 2 +- examples/dynamic-context/provider.yaml | 2 +- examples/dynamic-resource/provider.yaml | 2 +- examples/fact-driven-batch/provider.yaml | 2 +- examples/facts-recovery/provider.yaml | 2 +- examples/getting-started/provider.yaml | 2 +- .../host-materialized-resource/provider.yaml | 2 +- .../independent-verification/provider.yaml | 2 +- examples/monitoring-loop/provider.yaml | 2 +- .../provider-registry/provider/provider.yaml | 2 +- examples/recovery/provider.yaml | 2 +- examples/review-gate/provider.yaml | 2 +- examples/shared-provider/provider.yaml | 2 +- examples/simple-skill/provider.yaml | 2 +- examples/subgraphs/provider.yaml | 2 +- package.json | 2 +- src/scaffold.ts | 2 +- templates/basic/provider.yaml | 2 +- tests/integration/cli.test.ts | 6 +-- tests/integration/examples.test.ts | 4 +- 30 files changed, 143 insertions(+), 41 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index bc57108..37e679b 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -4,6 +4,11 @@ All notable changes to Agent Graph are documented here. The project follows [Sem ## Unreleased +## 0.3.1 - 2026-10-13 + +- Raised the scaffold, template and example `compatibility.agentGraph` range to `^0.3.0`, and documented the 0.3.0 Resource protocol migration. +- The README, contributing, support and development guides link to the Agent Graph documentation on context4ai.org and describe the publishing steps. + ## 0.3.0 - 2026-08-31 - Replaced the misleading Resource v1/v2 split with three independent v1 protocols for file, Graph-action, and Host-action resources and locations. diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 168b77a..069580f 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -2,6 +2,8 @@ Thank you for helping improve Agent Graph. Contributions can include bug reports, protocol proposals, documentation, examples, tests, and implementation changes. +New to the project? Read [Why Graph Engineering](https://context4ai.org/context/pages/91e2679fb8eb437a1a32a70050351382.html) and [Authoring Graphs](https://context4ai.org/context/pages/b218404303adf13ace7561657d45483b.html) on the documentation site, then run the [`getting-started`](./examples/getting-started) example. + ## Before opening a pull request - Use GitHub Discussions for design questions, adoption questions, and ideas that are not yet actionable. diff --git a/DEVELOPMENT.md b/DEVELOPMENT.md index 694ab1f..6283fa3 100644 --- a/DEVELOPMENT.md +++ b/DEVELOPMENT.md @@ -1,6 +1,6 @@ # Development -This document is for contributors to the `agent-graph` toolchain. Product usage belongs in the [English](./docs/en/README.md) and [Chinese](./docs/zh-CN/README.md) user guides. Repository-wide Agent rules live in [AGENTS.md](./AGENTS.md). +This document is for contributors to the `agent-graph` toolchain. Product usage belongs in the [English](./docs/en/README.md) and [Chinese](./docs/zh-CN/README.md) user guides and on the [documentation site](https://context4ai.org/context/pages/91e2679fb8eb437a1a32a70050351382.html). Repository-wide Agent rules live in [AGENTS.md](./AGENTS.md). ## Requirements @@ -100,3 +100,12 @@ Then test the produced tarball in a clean temporary prefix: 6. inspect tarball contents for LICENSE, metadata, docs, schemas, templates, and path leaks. Do not publish from a dirty or unreviewed working tree. Package releases follow semantic versioning; Provider manifests are independently versioned by their authors. + +## Publishing + +1. Move the `Unreleased` entries in [CHANGELOG.md](./CHANGELOG.md) under the new version and bump `package.json`. +2. Merge the release pull request after CI passes. +3. Create a GitHub Release whose tag is exactly `v`. `.github/workflows/publish.yml` checks the tag against `package.json`, verifies the package and publishes it to npm through Trusted Publishing. +4. Confirm the result with `npm view @c4a/agent-graph@ version`. + +Never run `npm publish` from a local checkout. Author-facing advice on testing and publishing Providers is in [Testing and Publishing](https://context4ai.org/context/pages/2a26bc3e8f39cad36b9354cb975ec644.html). diff --git a/README.md b/README.md index 3697768..9ed3118 100644 --- a/README.md +++ b/README.md @@ -15,7 +15,7 @@ Agents usually have enough knowledge. The harder problem is knowing which part a > **When to use it:** Not every Skill needs a Graph; keep a short, single-session task in `SKILL.md`. Adopt Agent Graph when a host can supply trustworthy external facts and the work truly needs verifiable completion, cross-session recovery, or testable routing and human gates. -[简体中文](./README.zh-CN.md) · [User manual](./docs/en/README.md) · [Graph Engineering](./docs/en/graph-engineering.md) · [Contributing](./CONTRIBUTING.md) · [Development](./DEVELOPMENT.md) +[Documentation](https://context4ai.org/context/pages/91e2679fb8eb437a1a32a70050351382.html) · [简体中文](./README.zh-CN.md) · [User manual](./docs/en/README.md) · [Graph Engineering](./docs/en/graph-engineering.md) · [Contributing](./CONTRIBUTING.md) · [Development](./DEVELOPMENT.md) ## A simple example @@ -71,7 +71,7 @@ Agent Graph does not silently rewrite its own plan. Runtime routing follows the ## A real-world case: Context -[Context](https://github.com/context4ai/context) uses Agent Graph behind one thin public Agent entry: [`/c4a:context`](https://github.com/context4ai/context/blob/main/packages/context-cli/plugin/commands/context.md). The same entry starts a requested workspace or resumes an existing one: `context entry` resolves initialization, workspace relocation, or current workflow evaluation, then the Agent follows `workflow.current`. Phase-specific procedures, Actions, and Resources remain separate, while the Agent receives, reads, and proves consumption of exactly what the selected Route requires. Re-entering the entry with unchanged Facts selects the same Route; completed evidence advances or no-ops, and revision-bound host commands reject stale writes. This gives Agent work an explicit idempotency boundary across retries and new turns. Its debug recording makes every selected Route, loop, Gate, and outcome replayable. +[Context](https://github.com/context4ai/context) runs its whole knowledge workflow on Agent Graph behind one thin production entry, [`/c4a:context`](https://github.com/context4ai/context/blob/main/plugins/context/skills/context/SKILL.md). The entry starts a new workspace or resumes an existing one; each evaluation hands the Agent only the procedures and resources the selected Route requires, and the Agent proves it read them. Re-entering with unchanged Facts selects the same Route, and revision-bound commands reject stale writes, so retries and new sessions are safe. Debug recordings make every Route, loop, Gate and Outcome replayable. [Agent Graph in Context](https://context4ai.org/context/pages/e0028d6618a071cc8e8f14135d034285.html) walks through the integration. [Watch the interactive replay](https://context4ai.github.io/context/case-studies/workflow/?lang=en) · [Read the case study](https://github.com/context4ai/context/blob/main/docs/en/case-studies/agent-graph-workflow.md) @@ -146,11 +146,19 @@ All three fields are required and validated together. `path:` always resolves re The Skill body keeps only this bootstrap and consumption contract. Phase-specific procedures, schemas, and context remain Route resources and are loaded on demand instead of being copied into the Skill. The binding selects a stable workflow; current modules, batches, and dates are runtime Facts. See [Skills and Providers](./docs/en/skills-and-providers.md) for the complete contract. -A host may attach current-conversation resource read receipts when resolving a Route. Exact static digests can then remain `current` across steps, while revision-bound dynamic views become `read-required` after the workflow revision changes. Receipts reduce repeated reading; they never prove that an Action completed. +Hosts can also attach resource read receipts to avoid repeated reading, and can serve Host-action Resources produced by their own handlers; the [specification](./docs/en/specification.md) defines both contracts. -For a Host-action Resource, the Route carries a stable Handler plus versioned input/output contracts. Agent Graph computes the input correlation digest, validates the returned inline/resource envelope, and leaves execution, output-schema validation, trust policy, and durable recovery storage to the integrating host. +## Documentation -## Documentation and reference +The [Agent Graph documentation](https://context4ai.org/context/pages/91e2679fb8eb437a1a32a70050351382.html) on the Context site explains the model and walks through real use: + +| Section | Pages | +|---|---| +| How It Works | [Why Graph Engineering](https://context4ai.org/context/pages/91e2679fb8eb437a1a32a70050351382.html) · [Core Model](https://context4ai.org/context/pages/ad65c836debb540be355e741aabf3dcf.html) · [Runs and Recovery](https://context4ai.org/context/pages/708a22de19d0b807fd512451f1269434.html) · [Skills and Providers](https://context4ai.org/context/pages/b3558e7c73749da60cf1b9634061fdd8.html) · [Agent Graph in Context](https://context4ai.org/context/pages/e0028d6618a071cc8e8f14135d034285.html) | +| Guides | [Getting Started](https://context4ai.org/context/pages/05958f2aaec0c5605023f05e067c37bf.html) · [Authoring Graphs](https://context4ai.org/context/pages/b218404303adf13ace7561657d45483b.html) · [Testing and Publishing](https://context4ai.org/context/pages/2a26bc3e8f39cad36b9354cb975ec644.html) | +| Reference | [Specification](https://context4ai.org/context/pages/098719903f2a7dcec5c1a6edb7b8ead3.html) · [CLI and SDK](https://context4ai.org/context/pages/7e7db2502a06c2f284c1701cc591c32b.html) · [Migration](https://context4ai.org/context/pages/516592ea7ac3e03cb284d8283bf349fc.html) | + +The versioned user manual ships with this repository and is the normative reference for each release: - [Getting started](./docs/en/getting-started.md) - [Authoring graphs](./docs/en/authoring.md) @@ -168,3 +176,26 @@ To inspect the repository directly: - [`examples/`](./examples) contains complete runnable scenarios; start with [`getting-started`](./examples/getting-started); - [`schemas/`](./schemas) contains the machine-readable protocol contracts used by tools and integrations. + +## Ecosystem + +| Project | Role | +|---|---| +| [Context](https://github.com/context4ai/context) | Knowledge workflow for engineering teams and their Agents; the largest Agent Graph integration | +| [Source Graph](https://github.com/context4ai/sourcegraph) | Code search and reading at pinned Git revisions | +| [Portal](https://github.com/context4ai/portal) | [context4ai.org](https://context4ai.org), including the documentation site | + +## Contributing + +```bash +git clone https://github.com/context4ai/agent-graph.git +cd agent-graph +bun install +bun run verify +``` + +Read [CONTRIBUTING.md](./CONTRIBUTING.md) before opening a pull request and [DEVELOPMENT.md](./DEVELOPMENT.md) for the source layout, protocol rules and release audit. Ask questions in [GitHub Discussions](https://github.com/context4ai/agent-graph/discussions) (see [SUPPORT.md](./SUPPORT.md)), and report vulnerabilities through [SECURITY.md](./SECURITY.md). Participation is governed by the [Code of Conduct](./CODE_OF_CONDUCT.md). Release history is in [CHANGELOG.md](./CHANGELOG.md). + +## License + +[MIT](./LICENSE) diff --git a/README.zh-CN.md b/README.zh-CN.md index cbc8dd7..236814b 100644 --- a/README.zh-CN.md +++ b/README.zh-CN.md @@ -15,7 +15,7 @@ Agent 很多时候并不缺知识。更难的是判断：现在该读哪一部 > **什么时候该用：** 不是每个 Skill 都需要 Graph；单轮、短流程，靠一份 `SKILL.md` 就能完成时，保持简单。只有当宿主能提供可信的外部事实，并且任务确实需要可验证完成、跨会话恢复，或可测试的路由与人工门禁时，再引入 Agent Graph。 -[English](./README.md) · [用户手册](./docs/zh-CN/README.md) · [Graph Engineering](./docs/zh-CN/graph-engineering.md) · [贡献指南](./CONTRIBUTING.md) · [开发指南](./DEVELOPMENT.md) +[文档](https://context4ai.org/context/pages/91e2679fb8eb437a1a32a70050351382.html) · [English](./README.md) · [用户手册](./docs/zh-CN/README.md) · [Graph Engineering](./docs/zh-CN/graph-engineering.md) · [贡献指南](./CONTRIBUTING.md) · [开发指南](./DEVELOPMENT.md) ## 先看一个最简单的例子 @@ -71,7 +71,7 @@ Agent Graph 不会在后台擅自重写自己的计划。运行时路由随证 ## 真实实践：Context -[Context](https://github.com/context4ai/context) 通过一个薄的公开 Agent 入口使用 Agent Graph：[`/c4a:context`](https://github.com/context4ai/context/blob/main/packages/context-cli/plugin/commands/context.md)。同一个入口既能创建用户请求的工作区，也能继续已有工作区：`context entry` 负责判断初始化、工作区定位或当前工作流求值，Agent 随后跟随 `workflow.current`。各阶段的 Procedure、Action 和 Resource 保持分离，Agent 只接收当前 Route 精确要求的内容，并以读取回执证明已经消费。Facts 不变时，重新进入仍会选中同一条 Route；已有完成证据会推进或 no-op，绑定 revision 的宿主命令则拒绝过期写入。这样，Agent 在重试和新回合之间拥有明确的幂等边界。它的调试记录可以回放每一条 Route、循环、门禁和最终结果。 +[Context](https://github.com/context4ai/context) 的整个知识工作流都运行在 Agent Graph 上，对外只有一个薄的生产入口 [`/c4a:context`](https://github.com/context4ai/context/blob/main/plugins/context/skills/context/SKILL.md)。该入口既能创建新工作区，也能继续已有工作区；每次求值只把当前 Route 需要的规程与资源交给 Agent，并要求 Agent 证明已经读取。Facts 不变时重新进入仍选中同一条 Route，绑定 revision 的命令会拒绝过期写入，因此重试与新会话都是安全的。调试记录可以回放每一条 Route、循环、门禁与结果。集成细节见 [Context 中的 Agent Graph](https://context4ai.org/context/pages/e0028d6618a071cc8e8f14135d034285.html)。 [观看交互式回放](https://context4ai.github.io/context/case-studies/workflow/?lang=zh) · [阅读完整案例](https://github.com/context4ai/context/blob/main/docs/zh-CN/case-studies/agent-graph-workflow.md) @@ -146,11 +146,19 @@ metadata: Skill 正文只保留这段启动与消费规则。各阶段的操作说明、Schema 和上下文继续作为 Route 资源按需加载，不复制进 Skill。绑定只选择稳定工作流；当前模块、批次或日期属于运行时 Facts。完整规则参见 [Skill 与 Provider](./docs/zh-CN/skills-and-providers.md)。 -宿主解析 Route 时可以附带当前会话的资源读取收据。内容摘要未变的静态资源可在后续步骤保持 `current`，绑定 Revision 的动态视图则会在工作流 Revision 变化后重新变成 `read-required`。收据只减少重复读取，不能证明 Action 已完成。 +宿主还可以附带资源读取收据以减少重复读取，并通过自身 Handler 提供 Host-action Resource；两类契约见[协议规范](./docs/zh-CN/specification.md)。 -对于 Host-action Resource，Route 携带稳定 Handler 与版本化 Input/Output 契约。Agent Graph 计算 Input 关联 Digest 并校验返回的 Inline/Resource Envelope；实际执行、Output Schema 校验、信任策略与持久恢复存储仍由集成宿主负责。 +## 文档 -## 文档与参考 +Context 文档站的 [Agent Graph 文档](https://context4ai.org/context/pages/91e2679fb8eb437a1a32a70050351382.html)讲解模型并结合真实用法逐步演示（与英文共用地址，按语言偏好显示中文）： + +| 分类 | 页面 | +|---|---| +| 原理 | [为什么是 Graph Engineering](https://context4ai.org/context/pages/91e2679fb8eb437a1a32a70050351382.html) · [核心模型](https://context4ai.org/context/pages/ad65c836debb540be355e741aabf3dcf.html) · [运行与恢复](https://context4ai.org/context/pages/708a22de19d0b807fd512451f1269434.html) · [Skills 与 Providers](https://context4ai.org/context/pages/b3558e7c73749da60cf1b9634061fdd8.html) · [Context 中的 Agent Graph](https://context4ai.org/context/pages/e0028d6618a071cc8e8f14135d034285.html) | +| 指南 | [快速开始](https://context4ai.org/context/pages/05958f2aaec0c5605023f05e067c37bf.html) · [编写 Graph](https://context4ai.org/context/pages/b218404303adf13ace7561657d45483b.html) · [测试与发布](https://context4ai.org/context/pages/2a26bc3e8f39cad36b9354cb975ec644.html) | +| 参考 | [规范](https://context4ai.org/context/pages/098719903f2a7dcec5c1a6edb7b8ead3.html) · [CLI 与 SDK](https://context4ai.org/context/pages/7e7db2502a06c2f284c1701cc591c32b.html) · [迁移](https://context4ai.org/context/pages/516592ea7ac3e03cb284d8283bf349fc.html) | + +带版本的用户手册随本仓库发布，是各版本的规范性参考： - [快速开始](./docs/zh-CN/getting-started.md) - [编写 Graph](./docs/zh-CN/authoring.md) @@ -168,3 +176,26 @@ Skill 正文只保留这段启动与消费规则。各阶段的操作说明、Sc - [`examples/`](./examples)：可运行的完整场景，第一次阅读可以从 [`getting-started`](./examples/getting-started) 开始； - [`schemas/`](./schemas)：供工具和集成使用的机器可读协议契约。 + +## 生态 + +| 项目 | 角色 | +|---|---| +| [Context](https://github.com/context4ai/context) | 面向研发团队与 Agent 的知识工作流，也是规模最大的 Agent Graph 集成 | +| [Source Graph](https://github.com/context4ai/sourcegraph) | 固定 Git 版本的代码搜索与阅读 | +| [Portal](https://github.com/context4ai/portal) | [context4ai.org](https://context4ai.org)，包括文档站 | + +## 参与贡献 + +```bash +git clone https://github.com/context4ai/agent-graph.git +cd agent-graph +bun install +bun run verify +``` + +提交 Pull Request 前请阅读 [CONTRIBUTING.md](./CONTRIBUTING.md)；源码结构、协议规则与发布审计见 [DEVELOPMENT.md](./DEVELOPMENT.md)。使用问题请到 [GitHub Discussions](https://github.com/context4ai/agent-graph/discussions)（见 [SUPPORT.md](./SUPPORT.md)），安全漏洞按 [SECURITY.md](./SECURITY.md) 报告。参与本项目须遵守[行为准则](./CODE_OF_CONDUCT.md)。版本历史见 [CHANGELOG.md](./CHANGELOG.md)。 + +## 许可证 + +[MIT](./LICENSE) diff --git a/SUPPORT.md b/SUPPORT.md index a4345d1..f13ab0d 100644 --- a/SUPPORT.md +++ b/SUPPORT.md @@ -2,7 +2,7 @@ Choose the channel that matches the request: -- Read the [user manual](./docs/en/README.md) or [中文手册](./docs/zh-CN/README.md) for product behavior and examples. +- Read the [documentation site](https://context4ai.org/context/pages/91e2679fb8eb437a1a32a70050351382.html), the [user manual](./docs/en/README.md) or the [中文手册](./docs/zh-CN/README.md) for product behavior and examples. - Use [GitHub Discussions](https://github.com/context4ai/agent-graph/discussions) for usage questions, integration design, and ideas. - Open a [bug report](https://github.com/context4ai/agent-graph/issues/new/choose) for reproducible defects. - Follow [SECURITY.md](./SECURITY.md) for vulnerabilities. diff --git a/docs/en/migration.md b/docs/en/migration.md index 08ca5f4..b384f51 100644 --- a/docs/en/migration.md +++ b/docs/en/migration.md @@ -2,6 +2,18 @@ Import creates a draft; it cannot infer business or safety semantics from file order alone. +## Resource protocol changes in 0.3.0 + +`0.3.0` removes `agent-graph.resource.v1`, `agent-graph.resource.v2`, `agent-graph.resource-location.v1`, and `agent-graph.resource-location.v2`. Each Resource and serialized Location now names its materialization authority: + +| Resource | Resource protocol | Location protocol | +|---|---|---| +| Static file read from the Provider | `agent-graph.resource.file.v1` | `agent-graph.resource-location.file.v1` | +| Materialized by a Graph-declared command or script | `agent-graph.resource.graph-action.v1` | `agent-graph.resource-location.graph-action.v1` | +| Materialized by the host | `agent-graph.resource.host-action.v1` | `agent-graph.resource-location.host-action.v1` | + +Replace each old identifier with the protocol for its actual authority, raise `compatibility.agentGraph` to `^0.3.0`, and run `agent-graph validate`. Old identifiers are rejected as `schema-invalid`. [`examples/host-materialized-resource`](../../examples/host-materialized-resource) shows a Host-action Resource. + ## Package contract changes in 0.2.0 `0.2.0` is a pre-1.0 contract-tightening release: diff --git a/docs/en/specification.md b/docs/en/specification.md index ab1e11a..46d2b6f 100644 --- a/docs/en/specification.md +++ b/docs/en/specification.md @@ -13,7 +13,7 @@ graphs: catalogs: codes: codes.yaml compatibility: - agentGraph: ^0.2.0 + agentGraph: ^0.3.0 node: ">=20" ``` @@ -360,7 +360,7 @@ Evaluation is read-only. Same definitions and routing inputs produce the same re - action identity and effect; - command plan or host handler; - resolved working directory plus its `workspace` or `provider` semantic origin; -- required and recommended resource locations, preserving the complete v1 or v2 materialization envelope; +- required and recommended resource locations, preserving the complete file, Graph-action, or Host-action location envelope; - `readState` on each Route Resource, distinguishing current-conversation content from content that must be loaded; - `afterAction.recordNode` and the requirement to evaluate again. @@ -403,7 +403,7 @@ The bundle is relocatable and can itself be loaded through `manifest.json`. Load Unknown fields are rejected in v1 objects. This prevents misspelled safety fields from being ignored. -Until the npm package reaches `1.0.0`, the `agent-graph.*.v1` family is still in its public draft finalization period. A `0.x` release may tighten a required field or invariant under semantic-versioning rules, but must document the break and update every shipped template, example, and test. `0.2.0` makes Action and Gate `reasonCode` mandatory and completes the Skill binding with explicit Graph and Entry fields. +Until the npm package reaches `1.0.0`, the `agent-graph.*.v1` family is still in its public draft finalization period. A `0.x` release may tighten a required field or invariant under semantic-versioning rules, but must document the break and update every shipped template, example, and test. `0.2.0` makes Action and Gate `reasonCode` mandatory and completes the Skill binding with explicit Graph and Entry fields. `0.3.0` replaces the numbered Resource and Resource Location protocols with separate file, Graph-action, and Host-action protocols. After the `1.0.0` stability boundary, incompatible new semantics require a new schema version; compatible additions require an explicitly defined extension point. Agent hosts should branch on schema, status codes, reason codes, and diagnostic codes, never on human descriptions. diff --git a/docs/zh-CN/migration.md b/docs/zh-CN/migration.md index 86481a9..c3d3521 100644 --- a/docs/zh-CN/migration.md +++ b/docs/zh-CN/migration.md @@ -2,6 +2,18 @@ Import 只生成草案，不能仅根据文件顺序推断业务或安全语义。 +## 0.3.0 Resource 协议变化 + +`0.3.0` 移除了 `agent-graph.resource.v1`、`agent-graph.resource.v2`、`agent-graph.resource-location.v1` 与 `agent-graph.resource-location.v2`。每个 Resource 及其序列化的 Location 都要写明物化权限归属： + +| Resource | Resource 协议 | Location 协议 | +|---|---|---| +| 从 Provider 读取的静态文件 | `agent-graph.resource.file.v1` | `agent-graph.resource-location.file.v1` | +| 由 Graph 声明的命令或脚本物化 | `agent-graph.resource.graph-action.v1` | `agent-graph.resource-location.graph-action.v1` | +| 由宿主物化 | `agent-graph.resource.host-action.v1` | `agent-graph.resource-location.host-action.v1` | + +按实际的物化权限替换旧标识，把 `compatibility.agentGraph` 提高到 `^0.3.0`，再执行 `agent-graph validate`。旧标识会以 `schema-invalid` 被拒绝。Host-action Resource 的写法见 [`examples/host-materialized-resource`](../../examples/host-materialized-resource)。 + ## 0.2.0 包契约变化 `0.2.0` 是一次发生在 1.0 前的契约收紧： diff --git a/docs/zh-CN/specification.md b/docs/zh-CN/specification.md index 1d92b0c..6d3814a 100644 --- a/docs/zh-CN/specification.md +++ b/docs/zh-CN/specification.md @@ -13,7 +13,7 @@ graphs: catalogs: codes: codes.yaml compatibility: - agentGraph: ^0.2.0 + agentGraph: ^0.3.0 node: ">=20" ``` @@ -360,7 +360,7 @@ Evaluation 是只读操作。相同定义与路由输入必须得到相同 Revis - Action 身份和 effect； - Command Plan 或 Host Handler； - 解析后的工作目录，以及其 `workspace` 或 `provider` 语义来源； -- required 与 recommended Resource Location，完整保留 v1 或 v2 物化 Envelope； +- required 与 recommended Resource Location，完整保留 file、Graph-action 或 Host-action Location Envelope； - 每个 Route Resource 的 `readState`，用于区分当前会话已读内容与必须加载的内容； - `afterAction.recordNode` 和重新 evaluate 的要求。 @@ -403,7 +403,7 @@ Bundle 可迁移，并可直接通过 `manifest.json` 重新加载。加载时 v1 对象会拒绝未知字段，避免拼错安全字段却被静默忽略。 -在 npm 包到达 `1.0.0` 前，`agent-graph.*.v1` 协议族仍处于公开草案定稿期。按照语义化版本规则，`0.x` 版本可以收紧必填字段或不变量，但必须记录破坏性变化，并同步全部随包模板、示例与测试。`0.2.0` 将 Action 和 Gate 的 `reasonCode` 设为必填，并用显式 Graph 和 Entry 字段补全 Skill Binding。 +在 npm 包到达 `1.0.0` 前，`agent-graph.*.v1` 协议族仍处于公开草案定稿期。按照语义化版本规则，`0.x` 版本可以收紧必填字段或不变量，但必须记录破坏性变化，并同步全部随包模板、示例与测试。`0.2.0` 将 Action 和 Gate 的 `reasonCode` 设为必填，并用显式 Graph 和 Entry 字段补全 Skill Binding。`0.3.0` 用相互独立的 file、Graph-action 与 Host-action 协议取代按编号区分的 Resource 与 Resource Location 协议。 到达 `1.0.0` 稳定边界后，不兼容的新语义必须使用新的 Schema 版本；兼容扩展必须使用明确声明的扩展点。Agent Host 应按 Schema、状态码、reason code 和 diagnostic code 分支，不能按人类描述文本分支。 diff --git a/examples/choice-routing/provider.yaml b/examples/choice-routing/provider.yaml index 63820e5..ceb1e7f 100644 --- a/examples/choice-routing/provider.yaml +++ b/examples/choice-routing/provider.yaml @@ -3,5 +3,5 @@ id: example.choice-routing version: 0.1.0 graphs: [graphs/choice.yaml] compatibility: - agentGraph: ^0.2.0 + agentGraph: ^0.3.0 node: ">=20" diff --git a/examples/dynamic-context/provider.yaml b/examples/dynamic-context/provider.yaml index 7a67777..0693552 100644 --- a/examples/dynamic-context/provider.yaml +++ b/examples/dynamic-context/provider.yaml @@ -3,5 +3,5 @@ id: example.dynamic-context version: 0.1.0 graphs: [graphs/main.yaml] compatibility: - agentGraph: ^0.2.0 + agentGraph: ^0.3.0 node: ">=20" diff --git a/examples/dynamic-resource/provider.yaml b/examples/dynamic-resource/provider.yaml index ddf3b5b..33c4786 100644 --- a/examples/dynamic-resource/provider.yaml +++ b/examples/dynamic-resource/provider.yaml @@ -3,5 +3,5 @@ id: example.dynamic-resource version: 0.1.0 graphs: [graphs/diagnose.yaml] compatibility: - agentGraph: ^0.2.0 + agentGraph: ^0.3.0 node: ">=20" diff --git a/examples/fact-driven-batch/provider.yaml b/examples/fact-driven-batch/provider.yaml index 94a6774..5378ee2 100644 --- a/examples/fact-driven-batch/provider.yaml +++ b/examples/fact-driven-batch/provider.yaml @@ -5,5 +5,5 @@ graphs: [graphs/main.yaml] catalogs: codes: codes.yaml compatibility: - agentGraph: ^0.2.0 + agentGraph: ^0.3.0 node: ">=20" diff --git a/examples/facts-recovery/provider.yaml b/examples/facts-recovery/provider.yaml index d39d1ce..4387957 100644 --- a/examples/facts-recovery/provider.yaml +++ b/examples/facts-recovery/provider.yaml @@ -3,5 +3,5 @@ id: example.facts-recovery version: 0.1.0 graphs: [graphs/build.yaml] compatibility: - agentGraph: ^0.2.0 + agentGraph: ^0.3.0 node: ">=20" diff --git a/examples/getting-started/provider.yaml b/examples/getting-started/provider.yaml index 032f086..10ed339 100644 --- a/examples/getting-started/provider.yaml +++ b/examples/getting-started/provider.yaml @@ -4,5 +4,5 @@ version: 0.1.0 description: Minimal agent-led workflow. graphs: [graphs/main.yaml] compatibility: - agentGraph: ^0.2.0 + agentGraph: ^0.3.0 node: ">=20" diff --git a/examples/host-materialized-resource/provider.yaml b/examples/host-materialized-resource/provider.yaml index cf5aae9..b5196fc 100644 --- a/examples/host-materialized-resource/provider.yaml +++ b/examples/host-materialized-resource/provider.yaml @@ -3,5 +3,5 @@ id: example.host-materialized-resource version: 0.1.0 graphs: [graphs/main.yaml] compatibility: - agentGraph: ^0.2.0 + agentGraph: ^0.3.0 node: ">=20" diff --git a/examples/independent-verification/provider.yaml b/examples/independent-verification/provider.yaml index 0b44ce7..f421b99 100644 --- a/examples/independent-verification/provider.yaml +++ b/examples/independent-verification/provider.yaml @@ -3,5 +3,5 @@ id: example.independent-verification version: 0.1.0 graphs: [graphs/main.yaml] compatibility: - agentGraph: ^0.2.0 + agentGraph: ^0.3.0 node: ">=20" diff --git a/examples/monitoring-loop/provider.yaml b/examples/monitoring-loop/provider.yaml index fadcba5..0879ccf 100644 --- a/examples/monitoring-loop/provider.yaml +++ b/examples/monitoring-loop/provider.yaml @@ -3,5 +3,5 @@ id: example.monitoring-loop version: 0.1.0 graphs: [graphs/monitor.yaml] compatibility: - agentGraph: ^0.2.0 + agentGraph: ^0.3.0 node: ">=20" diff --git a/examples/provider-registry/provider/provider.yaml b/examples/provider-registry/provider/provider.yaml index b1910fd..353351b 100644 --- a/examples/provider-registry/provider/provider.yaml +++ b/examples/provider-registry/provider/provider.yaml @@ -3,5 +3,5 @@ id: shared.provider version: 0.1.0 graphs: [graphs/main.yaml] compatibility: - agentGraph: ^0.2.0 + agentGraph: ^0.3.0 node: ">=20" diff --git a/examples/recovery/provider.yaml b/examples/recovery/provider.yaml index 3543331..6443c18 100644 --- a/examples/recovery/provider.yaml +++ b/examples/recovery/provider.yaml @@ -3,5 +3,5 @@ id: example.recovery version: 0.1.0 graphs: [graphs/recovery.yaml] compatibility: - agentGraph: ^0.2.0 + agentGraph: ^0.3.0 node: ">=20" diff --git a/examples/review-gate/provider.yaml b/examples/review-gate/provider.yaml index e7de448..44cfbad 100644 --- a/examples/review-gate/provider.yaml +++ b/examples/review-gate/provider.yaml @@ -3,5 +3,5 @@ id: example.review-gate version: 0.1.0 graphs: [graphs/review.yaml] compatibility: - agentGraph: ^0.2.0 + agentGraph: ^0.3.0 node: ">=20" diff --git a/examples/shared-provider/provider.yaml b/examples/shared-provider/provider.yaml index eb10eac..7bc8b81 100644 --- a/examples/shared-provider/provider.yaml +++ b/examples/shared-provider/provider.yaml @@ -5,5 +5,5 @@ graphs: [graphs/release.yaml] catalogs: codes: codes.yaml compatibility: - agentGraph: ^0.2.0 + agentGraph: ^0.3.0 node: ">=20" diff --git a/examples/simple-skill/provider.yaml b/examples/simple-skill/provider.yaml index 93887e1..0899694 100644 --- a/examples/simple-skill/provider.yaml +++ b/examples/simple-skill/provider.yaml @@ -3,5 +3,5 @@ id: example.simple-skill version: 0.1.0 graphs: [graphs/main.yaml] compatibility: - agentGraph: ^0.2.0 + agentGraph: ^0.3.0 node: ">=20" diff --git a/examples/subgraphs/provider.yaml b/examples/subgraphs/provider.yaml index ac05ff7..e8002aa 100644 --- a/examples/subgraphs/provider.yaml +++ b/examples/subgraphs/provider.yaml @@ -5,5 +5,5 @@ graphs: - graphs/main.yaml - graphs/quality.yaml compatibility: - agentGraph: ^0.2.0 + agentGraph: ^0.3.0 node: ">=20" diff --git a/package.json b/package.json index 9706159..853e88c 100644 --- a/package.json +++ b/package.json @@ -1,6 +1,6 @@ { "name": "@c4a/agent-graph", - "version": "0.3.0", + "version": "0.3.1", "description": "Graph Engineering for Agent Skills: model-free work contracts for fact-grounded routing, progressive context, and recoverable execution.", "type": "module", "packageManager": "bun@1.3.9", diff --git a/src/scaffold.ts b/src/scaffold.ts index d8532bc..a9a425a 100644 --- a/src/scaffold.ts +++ b/src/scaffold.ts @@ -77,7 +77,7 @@ export async function initProvider(directory: string, id: string): Promise=20" }, + compatibility: { agentGraph: "^0.3.0", node: ">=20" }, }; const action: ActionDefinition = { schema: "agent-graph.action.v1", diff --git a/templates/basic/provider.yaml b/templates/basic/provider.yaml index 7ae4ba3..8e4fd0e 100644 --- a/templates/basic/provider.yaml +++ b/templates/basic/provider.yaml @@ -6,5 +6,5 @@ graphs: catalogs: codes: codes.yaml compatibility: - agentGraph: ^0.2.0 + agentGraph: ^0.3.0 node: ">=20" diff --git a/tests/integration/cli.test.ts b/tests/integration/cli.test.ts index 699c41d..ba0394b 100644 --- a/tests/integration/cli.test.ts +++ b/tests/integration/cli.test.ts @@ -23,7 +23,7 @@ describe("built CLI", () => { test("runs as a Node executable and as a standalone copied file", async () => { const version = execute("node", ["dist/agent-graph.mjs", "--version"]); expect(version.status).toBe(0); - expect(version.stdout.trim()).toBe("0.3.0"); + expect(version.stdout.trim()).toBe("0.3.1"); const standalone = resolve(directory, "agent-graph.mjs"); await Bun.write(standalone, Bun.file(resolve(root, "dist/agent-graph.mjs"))); await chmod(standalone, 0o755); @@ -32,7 +32,7 @@ describe("built CLI", () => { expect(JSON.parse(validate.stdout).state).toBe("valid"); const bunVersion = execute(process.execPath, [standalone, "--version"], directory); expect(bunVersion.status).toBe(0); - expect(bunVersion.stdout.trim()).toBe("0.3.0"); + expect(bunVersion.stdout.trim()).toBe("0.3.1"); const extracted = resolve(directory, "graph.schema.json"); const schema = execute("node", [standalone, "schema", "extract", "graph", "--output", extracted, "--format", "json"], directory); expect(schema.status).toBe(0); @@ -47,7 +47,7 @@ describe("built CLI", () => { const cli = resolve(root, "dist/agent-graph.mjs"); expect(execute("node", [cli, "init", providerRoot, "--id", "cli-test", "--format", "json"]).status).toBe(0); const manifest = resolve(providerRoot, "provider.yaml"); - expect(await readFile(manifest, "utf8")).toContain("agentGraph: ^0.2.0"); + expect(await readFile(manifest, "utf8")).toContain("agentGraph: ^0.3.0"); expect(execute("node", [cli, "--manifest", manifest, "validate", "--format", "json"]).status).toBe(0); expect(execute("node", [cli, "--manifest", manifest, "test", resolve(providerRoot, "tests"), "--format", "json"]).status).toBe(0); expect(execute("node", [cli, "--manifest", manifest, "run", "start", "main", "--state", state, "--workspace", providerRoot, "--format", "json"]).status).toBe(0); diff --git a/tests/integration/examples.test.ts b/tests/integration/examples.test.ts index 471b5ee..e778cdf 100644 --- a/tests/integration/examples.test.ts +++ b/tests/integration/examples.test.ts @@ -24,7 +24,7 @@ describe("published examples", () => { test(`${name} validates and its graph cases pass`, async () => { const root = resolve(import.meta.dir, "../../examples", name); const provider = await loadProvider(resolve(root, "provider.yaml")); - expect(provider.manifest.compatibility?.agentGraph).toBe("^0.2.0"); + expect(provider.manifest.compatibility?.agentGraph).toBe("^0.3.0"); const results = await runGraphTests(provider, resolve(root, "tests")); expect(results.length).toBeGreaterThan(0); expect(results.filter((result) => !result.passed)).toEqual([]); @@ -41,6 +41,6 @@ describe("published examples", () => { expect(first.graph).toBe("main"); expect(first.entry).toBe("default"); const provider = await loadProvider(first.manifestPath); - expect(provider.manifest.compatibility?.agentGraph).toBe("^0.2.0"); + expect(provider.manifest.compatibility?.agentGraph).toBe("^0.3.0"); }); });