60 lines
2.7 KiB
Markdown
60 lines
2.7 KiB
Markdown
# ADR-003: Public-read source URL for fetch_oss_file
|
|
|
|
## Status
|
|
|
|
Accepted
|
|
|
|
## Date
|
|
|
|
2026-07-30
|
|
|
|
## Context
|
|
|
|
Controlled SuperAgent traces showed that `fetch_oss_file` accepts `object_uri` and `filename`. An `oss://`
|
|
request failed with `public_endpoint_missing`, while earlier HTTPS attempts reached file-type handling. The user
|
|
confirmed that the installed Tool reads a publicly accessible OSS address without a Provider and that the OSS
|
|
deployment is `public-read`.
|
|
|
|
The previous ARR adapter explicitly wrote every object with object ACL `private`. That overrides a public-read
|
|
bucket and would make a generated public URL unusable. At the same time, making every processing output public
|
|
would unnecessarily widen exposure.
|
|
|
|
## Decision
|
|
|
|
1. ARR requires the integration bucket to report bucket ACL `public-read`; anonymous writes remain forbidden.
|
|
2. Only `committed/source_xml/source.xml` is written with object ACL `public-read`. Staged objects, generated
|
|
reports, result JSON and exchange objects remain explicitly `private`.
|
|
3. `arr-opera-daily-program-input-3` includes a required `oss.url` generated by ARR as
|
|
`https://{bucket}.oss-{region}.aliyuncs.com/{encoded-object-key}`. It contains no query signature or secret.
|
|
4. The Main Prompt passes `oss.url` unchanged as `fetch_oss_file.object_uri` and the canonical attachment name
|
|
as `filename`, exactly once. It must not construct `oss://`, sign or substitute another URL.
|
|
5. XML extension/MIME acceptance remains a separate platform Tool configuration requirement.
|
|
|
|
## Rationale
|
|
|
|
ARR owns the bucket, endpoint and immutable object key, so it can generate one deterministic address without
|
|
asking the Agent to infer storage semantics. Object-level ACL selection satisfies anonymous source download
|
|
while keeping intermediate and output artifacts private.
|
|
|
|
## Consequences
|
|
|
|
- `fetch_oss_file` needs no OSS Provider, AccessKey or signed URL for this flow.
|
|
- A committed source XML is anonymously readable to anyone who has its URL; the URL is not a secret or an
|
|
authorization mechanism. Retention, access logging and public-source privacy review remain deployment duties.
|
|
- Readiness now rejects a private bucket for this integration.
|
|
- Deploying code and Prompt changes does not by itself allow XML; the platform must permit `.xml` and
|
|
`application/xml` if it still returns `extension_not_allowed`.
|
|
|
|
## Supersedes
|
|
|
|
- The private-object/credential-backed Provider assumption in earlier implementation notes and the historical
|
|
`oss://` Prompt experiment.
|
|
|
|
## Related
|
|
|
|
- `arr_processing/source_message.py`
|
|
- `arr_storage/aliyun_oss_v2.py`
|
|
- `prompts/arr_opera_daily_program_input.schema.json`
|
|
- `prompts/arr_opera_daily_main_agent_prompt.md`
|
|
- `.project-docs/50-evidence/topics/2026-07-30-superagent-fetch-oss-prompt-experiment.md`
|