"Vibe-Trading: Your Personal Trading Agent"
Python ai-agentalgorithmic-tradingbacktestingfintechllmmcpmulti-agentpythonquantitative-financetrading
feat(channels): pin the channel-authoring contract and document the recipe
Yufeng Hea57a71e16dba
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.mdindex bbaa220c7..b97a1acf6 100644--- a/CONTRIBUTING.md+++ b/CONTRIBUTING.md@@ -137,6 +137,34 @@ merging. Authors are strongly encouraged to self-check first.5. Open a PR. Every commit must include `Signed-off-by:` (use`git commit -s`). Reviewers will walk the checklist above.+## Adding a Channel (Quickstart)++Channels ship through one authoring contract; the Web UI renders any channel's+configuration with no per-channel frontend code.++1. Create `agent/src/channels/<name>.py` with a `BaseChannel` subclass:+ implement `start`, `stop`, and `send` (abstract), and `default_config()`+ returning the stored config shape. The registry (`src/channels/registry.py`)+ auto-discovers the module; delivery receipts, retries and manager wiring come+ from the base class and manager.+2. Field metadata lives in `agent/src/channels/config_meta.py`. Hand-written+ `FIELD_HINTS[name]` entries supply labels and authoritative secret flags;+ anything you omit is derived from `default_config()` with type inference, and+ credential-shaped keys are masked by the unconditional `SECRET_KEY_RE`+ fail-safe either way. If the platform has a credential endpoint, build the+ connection probe on `token_probe.py` rather than writing a new client (see+ `dingtalk_probe.py` for the pattern) and override `test_connection()`.+3. Run the authoring contract locally:+ ```bash+ pytest agent/tests/test_channel_authoring_contract.py -q+ ```+ It walks every discovered channel and fails when one breaks the recipe+ (abstracts unset, scalar config keys with no field hint, or an uncovered+ credential-shaped key that would leak unmasked into the form).+4. Open a PR with `Signed-off-by:` on every commit. Dict-valued config (e.g.+ per-group maps) stays file-configured by design; the generic form edits+ text/password/bool/list widgets only.+## Code Style- Format with `black`; lint with `ruff` (config in `pyproject.toml`).diff --git a/agent/tests/test_channel_authoring_contract.py b/agent/tests/test_channel_authoring_contract.pynew file mode 100644index 000000000..ae5c8b4c9--- /dev/null+++ b/agent/tests/test_channel_authoring_contract.py@@ -0,0 +1,67 @@+"""Every channel must satisfy the authoring contract (#1625).++A new channel ships as a ``BaseChannel`` subclass plus field metadata, and the+generic Web UI renders it with no per-channel frontend code. This suite walks+every built-in channel the registry discovers and checks the contract points+the UI and settings flows depend on, so a channel that breaks the recipe fails+here instead of in the browser.+"""++from __future__ import annotations++from src.channels.config_meta import SECRET_KEY_RE, channel_field_hints, is_secret_key+from src.channels.registry import discover_channel_names, load_channel_class+++def test_every_discovered_channel_satisfies_the_authoring_contract() -> None:+ names = discover_channel_names()+ assert names, "registry discovered no channels"++ checked = 0+ for name in names:+ try:+ cls = load_channel_class(name)+ except ImportError:+ # Optional stack not installed here (e.g. matrix needs [nio]); an+ # environment gate, not a contract violation.+ continue+ checked += 1++ # A concrete adapter: start/stop/send are abstract on BaseChannel.+ assert not cls.__abstractmethods__, f"{name} leaves BaseChannel abstracts unset"++ default_config = cls.default_config()+ assert isinstance(default_config, dict), f"{name} default_config is not a dict"++ # The generic form renders from hints; every configurable scalar key+ # must resolve one. Dict-valued fields are exempt by design: the form+ # cannot edit them, so they stay file-configured (see _derive_hints).+ hints = channel_field_hints(name)+ configurable = {k for k, v in default_config.items() if k != "enabled" and not isinstance(v, dict)}+ hint_keys = {h["key"] for h in hints}+ missing = configurable - hint_keys+ assert not missing, f"{name} has scalar config keys with no field hint: {sorted(missing)}"++ # Secret masking: hand-written hints are authoritative for their keys+ # (an audited declaration may subtract an over-match, e.g. websocket's+ # token_* path names); for every key no hint covers, the SECRET_KEY_RE+ # fail-safe must fire.+ hint_flags = {h["key"]: bool(h["secret"]) for h in hints}+ for key in configurable:+ if key in hint_flags:+ continue+ if SECRET_KEY_RE.search(key):+ assert is_secret_key(name, key), f"{name}.{key} is credential-shaped, uncovered by hints, and unmasked"+ for hint in hints:+ if hint["type"] == "password":+ assert hint["secret"], f"{name}.{hint['key']} is a password field not marked secret"++ assert checked > 0, "every discovered channel failed to import"+++def test_test_connection_envelope_shape_is_documented_by_default() -> None:+ # The base contract: a channel that does not override the probe reports+ # "unsupported" rather than crashing the settings UI.+ from src.channels.base import BaseChannel++ assert "test_connection" not in BaseChannel.__abstractmethods__