Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
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
34 changes: 17 additions & 17 deletions .agents/skills/json-prompt-solution/SKILL.md
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
---
name: json-prompt-solution
description: Add LLM-EdgeFlow prompt solutions and demos with complete JSON requests and responses at the C ABI boundary. Reuse nodes and text carriers; keep external field selection and response assembly in registered Adapters.
description: Add LLM-EdgeFlow prompt solutions and demos with complete JSON requests and responses at the Operator SDK boundary. Reuse nodes and text carriers; keep external field selection and response assembly in registered Adapters.
---

# JSON Prompt Solution
Expand All @@ -10,29 +10,29 @@ description: Add LLM-EdgeFlow prompt solutions and demos with complete JSON requ

## 先确定真正的 SDK 边界

本项目业务需求中的输入、输出指完整 C ABI 请求和响应,见根 `AGENTS.md` 与
[业务接入边界](../../../doc/dev_guide/business_onboarding.md#输入输出以-c-abi-为边界)。
传给 `Alg_Process` 输入结构体的字符串必须包含整个请求对象;输出应已由 Adapter
本项目业务需求中的输入、输出指完整 Operator 请求和响应,见根 `AGENTS.md` 与
[业务接入边界](../../../doc/dev_guide/business_onboarding.md#输入输出以-operator-sdk-为边界)。
传给 Operator `Process` 的输入槽位必须包含完整请求对象;输出由 OutputConverter
按业务契约组装完成。不能重新把边界解释为 Python、Demo 或内部节点端口。
输入是序列化对象文本,不给整个对象额外添加一层 JSON 字符串编码。

用户明确忽略的 version/endpoint/语言标识等字段不参与语义校验、路由或提示词构造。
业务契约由创建句柄时的注册业务类型与 Pipeline 绑定选定,不能擅自按 endpoint 分发。
业务契约由创建句柄时的注册业务绑定与 Pipeline 选定,不能擅自按 endpoint 分发。

## 选择最小实现范围

1. 按 `pipeline-composer` 查询目标构建的 Catalog 和 `describe-node`,核对实际端口、
模型和现有契约。不要从 prose 推断资源或为新提示词添加专用 LLM 节点。
2. 外部 JSON 字段契约不变时,增加或克隆 Pipeline、必要 `.conf` 和样例即可。
改变输入/输出字段契约时,按 `llm-edgeflow-developer-guide` 的 Integration 路径,
在注册 Adapter 内提取输入字段并序列化输出。Demo 只转换载体,不承担该业务语义。
3. 优先复用已有 C 结构、Operator ValueType、结果打包和运行器;有合适载体时无需再建
在注册 Converter 内提取输入字段并序列化输出。Demo 只转换载体,不承担该业务语义。
3. 优先复用已有 Operator 结构、ValueType、结果打包和运行器;有合适载体时无需再建
平台类型。不同业务可以复用载体,同时注册自己的契约,保持旧业务语义。
新生产 Adapter 需匹配 bridge,遵循业务接入指南中的注册完整性要求。
4. 按 `CONTRIBUTING.md` 判断 RFC;追加 C ABI 业务类型需记录接口决定,普通配置不需
遵循业务接入指南中的注册完整性要求。
4. 按 `CONTRIBUTING.md` 判断 RFC;追加新业务类型需记录接口决定,普通配置不需
额外审批。算法能力缺失时才考虑 custom Node,不把平台转换放进 Core 或 Nodes。

当前翻译参照 `doc/solutions/translate.md`、`src/adapter/biz/translate_adapter.cpp` 和
当前翻译参照 `doc/solutions/translate.md`、`src/adapter/biz/translate_bindings.cpp` 和
`configs/pipeline_translate_cpu.json`。其 `translate_v1` 复用既有文本/JSON 载体、一个
`LlmGenerateNode` 及模型实现。`sentence_text` / `entities_json` 是载体字段名称,不是业务
JSON 内的 query / translated;名称不够通用并不要求全仓改名。
Expand All @@ -44,29 +44,29 @@ JSON 内的 query / translated;名称不够通用并不要求全仓改名。
仅把约定原文交给提示词。翻译样例由 C++ JSON 解析器读取原始 `std::string`,经
`TextBatch` 直接交给生成节点;模型配置中的 system prompt 说明处理规则。
- 输出语义只有一个字符串时,优先让模型只生成结果原文,每条请求只调用一次生成。
C++ Adapter 用 JSON 序列化器组装字段,正确处理引号、换行、反斜杠和 NUL;不要用
C++ Converter 用 JSON 序列化器组装字段,正确处理引号、换行、反斜杠和 NUL;不要用
模型读取字段、拼协议、修复格式,也不要对模型原文擅自 trim、解析或去除包装。
该单次生成指一次文本生成调用,不是自回归解码只运行一个 token。
- 只有业务本身需要模型产生结构化语义时才引入结构化解析节点,校验字段与类型并使用
`failure_policy=fail`。SDK 响应组装始终留在 Adapter,不靠 Demo 投影字段。
`failure_policy=fail`。SDK 响应组装始终留在 Converter,不靠 Demo 投影字段。
不用固定示例或 fallback 冒充成功。
- `.conf` 必须指向新 Pipeline,检查模型路径覆盖、上下文与生成长度,以及 C ABI 固定
输出数组和 Operator 池容量的区别。原 Profile 不会自动指向新方案。
- `.conf` 必须指向新 Pipeline,检查模型路径覆盖、上下文与生成长度,以及 Operator
输出池容量配置。原 Profile 不会自动指向新方案。

## 验证与交付

- 重建注册,使用生产 `alg_pipeline_tool` 执行 Catalog、validate、plan、resolve-conf。
有意使用测试资产时全程选测试工具,不用测试工具绕过生产失败。
- 业务 I/O 契约变化时,扩展现有 Adapter/C ABI 套件,直接调用 `Alg_Process` 输入完整对象。
- 业务 I/O 契约变化时,扩展现有 Adapter/Operator 套件,直接调用 Operator `Process` 输入完整对象。
可用计数测试模型确定性验证原文输入、单次生成和 C++ 响应组装,再运行真实模型确认效果。
Operator Demo 共用 Adapter,但不等于调用过导出的 C ABI 入口;报告时区分两者
报告时记录实际验证链路
- 覆盖无关字段变化、缺失/非字符串字段、转义和空串、输出类型、来源、容量与失败状态。
不为每个提示词创建新测试框架或执行文件;沿用已有套件。
- 用本次配置运行用户样例,检查原生 ID、逐条状态、汇总和最终 JSON;再执行最终门禁。
没有权重时明确真实效果未验证,按项目资产清单准备资源,不把替身输出当效果。
- 按根 `AGENTS.md` 分别委派测试编写、编译、测试执行给不同子 agent,遵循源码依赖顺序,
由主 agent 实现和复核;交付流程仍以 `CONTRIBUTING.md` 为准。
- 交付一条可复制命令、C ABI 实际输入/输出示例、配置位置和准确的修改范围。
- 交付一条可复制命令、Operator 实际输入/输出示例、配置位置和准确的修改范围。
若复用旧载体名,说明其含义。未经用户要求不上传或创建 PR。

本 skill 保存复用决策,不维护节点/模型 Catalog;后续相似业务继续更新这一份指引。
4 changes: 2 additions & 2 deletions .agents/skills/llm-edgeflow-developer-guide/SKILL.md
Original file line number Diff line number Diff line change
@@ -1,13 +1,13 @@
---
name: llm-edgeflow-developer-guide
description: Route LLM-EdgeFlow implementation across Integration, Orchestration, Capability Nodes and Model Execution. Use for custom Nodes, platform I/O adapters and Operator bridges, Demo data conversion, Core, Models, Backends and verification; configuration-only solution work belongs to pipeline-composer.
description: Route LLM-EdgeFlow implementation across Integration, Orchestration, Capability Nodes and Model Execution. Use for custom Nodes, platform I/O converters and bindings, Demo data conversion, Core, Models, Backends and verification; configuration-only solution work belongs to pipeline-composer.
---

# LLM-EdgeFlow Developer Guide

First classify the requested change. Read only the references needed for the affected layer; do not load every reference by default.

- New modality, C ABI structure/function behavior, Adapter, Operator bridge, or allowed runtime Pipeline name: read [Integration](references/integration.md).
- New modality, Operator SDK structure/function behavior, Converter, IoBinding, or allowed runtime Pipeline name: read [Integration](references/integration.md).
- Demo dataset/carrier construction, result display or registration: follow [business onboarding](../../../doc/dev_guide/business_onboarding.md#统一-demo-接入). External request parsing and response assembly belong to Adapter work; load Integration for those changes even when the C carrier layout stays the same.
- Pipeline lifecycle, Validator, DAG planning, `AlgContext`, `BlackboardKey`, or session behavior: read [Orchestration](references/orchestration.md).
- New or modified capability Node, its parameters, or a Control handler: read [Capability Nodes](references/capability-nodes.md). Start Control work from the [compiled example](../../../doc/dev_guide/first_control.md); reuse transport and instance routing.
Expand Down
Original file line number Diff line number Diff line change
@@ -1,43 +1,31 @@
# Integration

Use this reference for new modalities, public C structures, Adapter behavior, business registration, or allowed Pipeline names.
Use this reference for new modalities, Operator structures, Converter behavior, business binding registration, or allowed Pipeline names.

Business input/output means the complete public C ABI request/response, including serialized
payload semantics. `Unpack` and Adapter packing must implement that contract inside the SDK;
Demo/Python cannot perform the missing field selection or response assembly. Reusing a C struct
does not imply payload compatibility. Follow [the boundary and carrier distinction](../../../../doc/dev_guide/business_onboarding.md#输入输出以-c-abi-为边界).
Business input/output means the complete public Operator SDK request/response, including serialized
payload semantics. `InputConverter::Decode` and `OutputConverter::Encode` must implement that contract inside the SDK;
Demo/Python cannot perform the missing field selection or response assembly. Reusing a host struct
does not imply payload compatibility. Follow [the boundary and carrier distinction](../../../../doc/dev_guide/business_onboarding.md#输入输出以-operator-sdk-为边界).

Start with [business onboarding](../../../../doc/dev_guide/business_onboarding.md) to select the requested
integration path. Reuse the Adapter when the external contract is unchanged; an existing C ABI
path edit does not automatically require a new Operator or Demo path. Adding a production
Adapter to the current shared SDK does require a matching bridge: Operator `GlobalInit` audits
all registered Adapters. For new Operator host types, also register ValueType capacity,
initialization and release. An ABI-only registration mode would require separate design.
integration path. Reuse the converters when the external contract is unchanged. Adding a production
binding to the current shared SDK requires matching input and output converters registered with `transport = "operator"`.
For new Operator host types, also register ValueType capacity, initialization and release.
Register ValueTypes and named single-object output allocators through
`adapter/operator_value_type.h`. Keep queue depth out of their callbacks. For multiple outputs
or config-selected nested payloads, follow the
[output allocation guide](../../../../doc/dev_guide/operator_output_allocation.md): each logical
slot selects its outer type, allocator and normalized parameters; map keys do not infer layout.
Keep configuration reading in Create-time Integration. `OutputConfigReader` selects fixed
enum fields and returns text; use `MakeOutputParameterParser<T>` with ordinary parameter
structs, without JSON in extension signatures or a `ToJson()` requirement. It is not a
Pipeline Node and does not run per request.
Use the existing `ResultPackingAdapter` and `MakeSingleSlotBizBridge` helpers where applicable;
the onboarding guide owns those implementation examples and optional Demo conversion steps.
Keep configuration reading in Create-time Integration. `OperatorConfigResolver` validates
slot configurations, allocator and capacities. It is not a Pipeline Node and does not run per request.

1. Public C ABI, Operator contract, or new modality changes meet the RFC threshold in
1. Public Operator contract or new modality changes meet the RFC threshold in
`CONTRIBUTING.md`. Map the external contract, ownership, cardinality, batch bounds, and
failure behavior before implementation.
2. Keep `include/edgeflow/c_api.h` valid C11. Its current platform data declarations come from `include/platform_mock/`; see that directory's README for the distinction from real company headers. Keep existing local mock DTOs and platform enums there, and keep framework entrypoints under `edgeflow/`. Expose only C primitives, fixed-layout C structs, pointers with documented ownership, and C enums through C headers—never STL or third-party types.
3. Preserve all six exported functions and their exception barrier in `src/adapter/c_api_adapter.cpp`: `noexcept`, `try`, `catch (const std::exception&)`, and `catch (...)`.
4. Implement biz conversion through `IBizAdapter` under `src/adapter/biz/`, using existing adapters as current patterns. Register through `REGISTER_BIZ_ADAPTER`; do not add a central dispatch switch.
5. Declare Adapter ingress/egress Blackboard ports and allowed runtime Pipeline names through its `BizDefinition` entries. The `biz_name` in Pipeline JSON must be accepted by the Adapter; a display name or Demo alias is not a substitute.
6. Copy input data when the ABI lifetime requires it, store request-scoped values in `AlgContext`, and pack output only through the documented ownership contract.
2. Operator public API lives in `include/edgeflow/operator/interface.h` and `types.h`. Platform mock types live in `include/platform_mock/operator_types.h` and `operator_data_types.h`; see that directory's README for the distinction from real company headers.
3. Preserve exported Operator functions and their exception barrier in `src/adapter/operator/operator_adapter.cpp`: `noexcept`, `try`, `catch (const std::exception&)`, and `catch (...)`.
4. Implement input conversion through `InputConverter` under `src/adapter/input/`, output conversion through `OutputConverter` under `src/adapter/output/`, and business binding through `IoBindingDefinition` under `src/adapter/biz/`. Register through `REGISTER_INPUT_CONVERTER`, `REGISTER_OUTPUT_CONVERTER`, and `REGISTER_IO_BINDING`.
5. Declare binding ingress/egress Blackboard ports and allowed runtime Pipeline names through its `BizExposureDefinition` and `IoBindingDefinition`. The `biz_name` in Pipeline JSON must match the binding.
6. Copy input data when the lifetime requires it, store request-scoped values in `AlgContext`, and pack output into leased pool slots only through the documented ownership contract.

Use `tests/contract/abi/test_adapter_contract_security.cpp`, `tests/contract/abi/test_c_abi_safety.cpp`, `tests/contract/abi/test_c11_abi_compliance.c`, and existing modality adapters as live templates. If the change also adds nodes, read `capability-nodes.md`; if it changes Core contract behavior, read `orchestration.md`.

RFC-0044 lifecycle: `Unpack` validates biz fields before converting to owned DTOs. The unused
internal `IBizAdapter::ValidateInput` hook was removed; migrate custom overrides into `Unpack`
and rebuild extensions. Reuse `adapter/biz_input_constraints.h` for channel/audio semantic limits.
Egress metadata describes the Adapter's internal consumption, including ranked aggregation;
retain runtime provenance and output-capacity checks after static validation.
Use `tests/contract/abi/test_cpp_operator_sdk.cpp`, `tests/contract/abi/test_operator_safety.cpp`, `tests/contract/abi/test_adapter_contract_security.cpp`, and existing modality converters as live templates. If the change also adds nodes, read `capability-nodes.md`; if it changes Core contract behavior, read `orchestration.md`.
Original file line number Diff line number Diff line change
Expand Up @@ -17,11 +17,9 @@ framework-specific evidence.
this is not a workaround for a failing production configuration. See
[tool selection](../../../../tools/pipeline_studio/README.md#校验工具选择).
4. When a business I/O contract changes, verify the complete original request and response by
directly calling `Alg_Process` in the existing C ABI/Adapter suite. Operator Demo success
alone does not prove that boundary; reuse existing coverage when the contract is unchanged.
directly calling Operator `Process` in the existing Operator/Adapter suite.
When a Demo-supported business path changes, run that edited Pipeline through the compatible
Demo and check request IDs, status and expected output fields. For a C ABI-only path, use the
corresponding end-to-end contract tests instead of adding a new Demo solely for verification. Follow
Demo and check request IDs, status and expected output fields. Follow
[running the current solution](../../../../tools/pipeline_studio/README.md#运行当前方案)
for `.conf` / Profile selection and Demo Control behavior; running an unchanged Profile
does not verify a new JSON file.
Expand Down
6 changes: 3 additions & 3 deletions .agents/skills/pipeline-composer/SKILL.md
Original file line number Diff line number Diff line change
Expand Up @@ -12,11 +12,11 @@ and native Resolver; do not reproduce their validation rules.

## Workflow

First compare the requested complete C ABI input/output contract with the existing Adapter.
The same C carrier layout is not enough: payload fields, types and serialization must also match.
First compare the requested complete Operator SDK input/output contract with the existing Adapter / Converters.
The same carrier layout is not enough: payload fields, types and serialization must also match.
Catalog ingress/egress are internal ports. A missing external conversion belongs in Integration;
do not compensate by extracting request fields or assembling business responses in Demo/Python.
See [the I/O boundary](../../../doc/dev_guide/business_onboarding.md#输入输出以-c-abi-为边界).
See [the I/O boundary](../../../doc/dev_guide/business_onboarding.md#输入输出以-operator-sdk-为边界).

1. Build the tool if unavailable, and rebuild after registration changes. Query the target biz
contract and its filtered assets:
Expand Down
4 changes: 2 additions & 2 deletions .github/workflows/ci.yml
Original file line number Diff line number Diff line change
Expand Up @@ -135,7 +135,7 @@ jobs:
./scripts/run_sanitizers.sh --ci-runtime

real-c-abi-and-profile:
name: Real GGUF C ABI & Profile
name: Real GGUF Operator & Profile
runs-on: ubuntu-latest

env:
Expand Down Expand Up @@ -198,7 +198,7 @@ jobs:
- name: Fetch and Verify Pinned GGUF
run: ./scripts/fetch_real_test_models.sh --gguf-only

- name: Run Real C ABI and Public Profile
- name: Run Real Model and Public Profile
run: |
ccache -z
LLM_EDGEFLOW_LINKER=mold \
Expand Down
Loading
Loading