Skip to content

docs: require Node README capability summaries #2

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
mrgh97 merged 2 commits into from
Oct 22, 2026
Merged

docs: require Node README capability summaries #2

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
95ce8d1
docs: define Node, Endpoint and Tool API capabilities
mrgh97 Oct 22, 2026
8c79461
docs: separate English and Chinese README files
mrgh97 Oct 22, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
62 changes: 62 additions & 0 deletions CONTRIBUTING.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -82,3 +82,65 @@ When filing an issue, include:

By contributing, you agree that your contributions are licensed under the Apache
License, Version 2.0.

## Node README contract

When creating or changing a downstream Adapter/Operator Node repository, maintain a
capability summary in its root README. Keep English in `README.md` and Simplified
Chinese in `README_zh.md`, with reciprocal language links at the top. Maintain the
same interface facts, commands and examples in both files in each change; do not
interleave translated prose within one README. This is a documentation requirement; it does
not require a data-plane Node to implement ToolEndpoint or HTTP.

Count independent production Dora Node entrypoints, not aliases, CLI subcommands,
classes, packages, test sinks, or fake plants. List debug/example Nodes separately.
For each supported mode, count concrete Endpoint IDs and their operations separately.
ToolSpec aliases and readiness are deployment concerns: never infer the number of
caller-visible Tools from the number of Nodes, Endpoints, or operations.

Required fields:

| Field | Required content |
| --- | --- |
| Production Nodes | Count, names, source/CLI and packaged entrypoints; aliases and optional modes |
| Auxiliary programs | Test/fake/example Nodes and offline CLI utilities, excluded from production count |
| Tool support | Data-plane only, provider, caller, Gateway, or an explicit combination; enabling configuration |
| Endpoints | Count and exact `endpoint_id`, provider Node, and descriptor source link; write `0` when absent |
| Operations | Per-Endpoint count and exact operation names; Query/Action/Session, concurrency, lifecycle controls |
| Direct HTTP Tool API | Method/path, body/result contract, errors and units, or `0 (via Gateway)`; unrelated APIs listed separately |
| Tool bindings | `tool_id -> endpoint_id / operation -> provider Node`; distinguish deployed examples from fixed contracts |
| Compatibility | Wire/schema versions, dependency locks, Gateway/Node build revisions and unsupported combinations |
| Source and examples | Descriptor/handler, dataflow, config, request/result schema, build instructions and release provenance |

Start with this Markdown template and replace every placeholder:

```markdown
## Node, Endpoint and Tool API

| Item | Implementation |
| --- | --- |
| Production Nodes | <count; names; source/CLI and packaged entrypoints> |
| Auxiliary programs | <debug Nodes, aliases and offline CLI utilities> |
| Tool support | <data-plane only / provider / caller / Gateway; activation mode> |
| Endpoints | <count; endpoint_id; provider Node; descriptor link> |
| Operations | <per-Endpoint count; operation; semantics; concurrency and controls> |
| Direct HTTP Tool API | <count and method/path table, or 0; Gateway owns external API> |
| Gateway Tools | <deployment-configured count; exact example config or no fixed Tool ID> |

<tool_id -> endpoint_id / operation -> provider Node mapping>
<request/result contract, units/frames, errors, config and source links>
<compatibility and build/release provenance>
```

A data-plane-only controller may consume Action-shaped Dora goal/feedback/result
messages without implementing a ToolEndpoint. A provider can expose several
operations at one Endpoint; a Gateway routes providers without becoming their
business Endpoint. Optional provider modes must document the non-provider default.
Session uses stop and Action uses cancel; accepted control is not a terminal result.

Before review, compare the README against package scripts, build outputs, descriptor,
handler registration, Gateway ToolSpec and dataflow. Update the summary in the same
change as any interface or capability change. Do not invent an HTTP URL for a Dora
provider, advertise a directory absent from the tree, or infer released-binary
capability from current source. Keep examples generic and exclude local machine
configuration, credentials, runtime records and private deployment details.
20 changes: 16 additions & 4 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,5 +1,7 @@
# Forge

[English](README.md) | [简体中文](README_zh.md)

Forge is a small robotics framework core for Dora dataflows. It provides shared
message schemas, Python and Rust message implementations, reusable node runner
helpers for robot drivers and policy nodes, and typed tool endpoint contracts.
Expand All @@ -21,7 +23,7 @@ This repository intentionally focuses on the framework layer:
- `packages/policy` provides policy implementation protocols and a standard Dora
Operator node loop.
- `packages/tool` provides dependency-free ToolEndpoint SPI and logical Wire models,
with embedded Query and Action handling; Session dispatch remains future work.
with embedded Query, Action, and Session handling.
- `packages/common` and `crates/forge_common` provide shared utilities,
including logging, tracing, and optional publish/receive observability.
- `packages/kinematics` provides optional Pinocchio-based URDF forward
Expand Down Expand Up @@ -66,6 +68,16 @@ Start with [`interfaces/forge_tool/README.md`](interfaces/forge_tool/README.md).
the architecture, normative Wire protocol, Python package guide, and canonical Arrow
schema without duplicating their contracts.

## Node repository documentation

Downstream Node repositories must document concrete Node entrypoints, Tool support,
Endpoint IDs, operations, direct HTTP APIs, and deployment Tool bindings in their root
README. Maintain separate English `README.md` and Simplified Chinese `README_zh.md`,
with reciprocal links and synchronized changes. Count Nodes, Endpoints, operations, and Gateway Tools separately; state `0` or
configuration-dependent behavior explicitly. Framework helpers are not deployed Nodes.
See the [Node README contract](CONTRIBUTING.md#node-readme-contract) for the required
fields, template, and review checklist.

## Observability documentation

Start with [`interfaces/observability/README.md`](interfaces/observability/README.md).
Expand Down Expand Up @@ -187,7 +199,7 @@ include(FetchContent)

FetchContent_Declare(
forge
GIT_REPOSITORY https://gitlab.ex-ai.cn/PhyAgentOS/framework/forge.git
GIT_REPOSITORY https://github.com/PhyAgentOS/forge.git
GIT_TAG forge-msgs-v2.0.0
SOURCE_SUBDIR cpp/forge_msgs
)
Expand All @@ -207,7 +219,7 @@ include(FetchContent)

FetchContent_Declare(
forge_common
GIT_REPOSITORY https://gitlab.ex-ai.cn/PhyAgentOS/framework/forge.git
GIT_REPOSITORY https://github.com/PhyAgentOS/forge.git
GIT_TAG forge-common-v2.1.0
SOURCE_SUBDIR cpp/forge_common
)
Expand All @@ -227,7 +239,7 @@ include(FetchContent)

FetchContent_Declare(
forge_robot
GIT_REPOSITORY https://gitlab.ex-ai.cn/PhyAgentOS/framework/forge.git
GIT_REPOSITORY https://github.com/PhyAgentOS/forge.git
GIT_TAG forge-robot-v2.0.0
SOURCE_SUBDIR cpp/forge_robot
)
Expand Down
Loading
Loading