星图源抽象设计

这份文档面向维护者和实现者，目标是把当前 --code 从“本机路径入口”升级成“统一源入口”，同时兼容命令行、本地交互、服务调用和订阅链路。

重点不是改星图语法，而是把“怎么定位一份星图内容”从单一路径模型升级成统一来源模型。

一句话目标：

把 code 从“路径模式”改成“来源模式”

先判断这页的范围

你只想知道 --code 现在怎么写：先看星图协议
你只想知道执行顺序、覆盖优先级和批跑控制语义：先看星图深入说明
你要把星图输入从本机路径升级成统一来源：看这里
你要让命令行、交互、服务调用和订阅链路共享同一套输入语义：看这里

当前问题

当前实现里，--code 的主语义仍然偏向“本机文件列表”。这会带来四类结构性问题。

1. 外部调用无法稳定引用端侧本机路径

外部系统通常只知道“要执行哪份星图”
它不应知道目标机器的目录结构、部署位置或文件同步方式
让调用方依赖本机路径，会把执行语义和部署细节绑死

2. 输入来源的协议语义不清

当前更像“请在本地打开某份文件执行”
这不是任务内容本身
这只是内容定位方式的一种

3. 多入口之间没有统一输入模型

命令行更偏本地文件
服务调用更适合直接传内容或可追踪来源
长链路订阅需要稳定、可恢复、可审计的来源标识

4. 安全与审计边界不清

本机路径天然带来目录越界和部署差异问题
远端来源又会引入鉴权、超时、缓存和来源可信度问题
如果没有统一来源抽象，后续每加一种入口都要重复补边界

设计目标

核心目标

--code 不再以“本机路径”作为唯一输入语义
所有入口统一收敛到同一种来源抽象
星图解析继续只消费文本，不感知来源差异
长链路任务下发可以承载内联内容、远端来源或平台制品

兼容目标

现有命令行本地文件用法继续可用
现有星图正文语法不变
现有批跑顺序、重试、前后置和规则行为不变
现有任务下发主协议不推翻，只扩展输入来源语义

非目标

不重写星图 DSL
不把 code 和 plan 合并
不在第一阶段强制引入完整的远端制品中心
不要求所有来源都必须持久缓存

总体方案

把 --code 的输入统一抽象成“来源列表”。所有入口先把调用方提供的内容解析成统一来源，再解析正文，再进入批跑执行面。

统一流程可以概括为：

入口层提供来源声明
解析层把来源解成可执行文本
星图解析层只消费文本
批跑执行层继续按原有语义运行

这里的关键变化是：

以前的批跑入口是“收路径，再读文件”
以后是“收来源，再解成文本”

支持的来源类型

建议支持以下几类来源：

本地文件

面向命令行兼容
适合本机快速执行
不适合作为外部协议主路径

标准输入

面向管道和动态拼装
适合临时生成的星图内容
仍然属于本机入口，不适合作为远端任务协议主语义

内联文本

面向服务调用、SDK 和最小可用任务提交
最适合不依赖本机文件的场景
也是外部调用最容易收敛的默认来源

远端文本来源

面向集中托管、跨环境复用和回归调度
需要鉴权、超时、白名单和缓存策略

平台制品

面向平台内部对象存储、附件中心或版本化蓝本
适合统一权限、统一追踪和统一版本管理
可以晚于内联文本和远端文本来源落地

统一输入边界

不管入口来自哪里，最终都应该表达同一件事：

这次执行要加载哪些来源
每个来源属于哪一类
是否需要额外的获取约束
结果里应该如何标识来源

入口层不应该再把“本机路径”当成唯一正式语义。
本机路径可以保留，但只能作为兼容来源，而不是统一协议主语义。

入口侧要求

命令行

继续兼容本地文件用法
可逐步增加标准输入、内联文本和远端来源
长期应以“显式来源”优先于“隐式字符串猜测”

本地交互

交互模式可以继续复用统一来源模型
不应该为交互模式单独发明另一套来源语义

服务调用

不应依赖端侧本机路径
更适合传内联内容、远端来源或平台制品

订阅链路

文本任务和来源列表应能并存
若两者同时存在，应定义稳定优先级
任务恢复、重放和审计都应基于统一来源模型

解析策略

来源解析层负责把不同来源收敛成统一文本输入。
它应该承担这些职责：

判断来源类型是否合法
获取或读取正文内容
做必要的大小限制和超时控制
生成稳定的来源标识
产生可回放、可审计的来源元信息

解析层不应该承担这些职责：

不解释星图 DSL 语义
不决定批跑顺序
不介入规则判断
不决定具体执行模式

缓存策略

只要支持远端来源或平台制品，就必须明确缓存边界。

建议目标：

降低重复获取远端来源的开销
让单轮批跑中的重复加载可以复用
让恢复链路中再次执行同一来源时能够稳定命中

建议原则：

缓存键基于规范化来源标识，而不是原始输入文本
本机兼容来源可以轻量缓存
远端来源和平台制品应支持可控 TTL
第一阶段只做进程内缓存即可
磁盘缓存属于可选增强，不应成为第一阶段前置依赖

安全与鉴权

只要放开远端来源，就必须明确安全约束。

建议原则：

默认只允许安全协议
默认限制可访问来源范围
默认隐藏敏感鉴权材料
默认限制响应体大小和跳转次数
不要把来源获取实现成无限制转发器

本机兼容来源也要保留边界：

不应允许越界读取
不应默认信任任意路径输入
不应让部署差异直接污染协议语义

超时与失败语义

不同来源应该有不同超时边界，但错误语义必须统一。

建议统一关注这些错误类别：

来源超时
鉴权失败
来源不存在
内容过大
来源类型不支持

错误结果里至少应保留：

来源类型
来源标识
人类可读的失败说明

可观测与审计

统一来源模型里，来源标识是必需能力。

至少要满足三件事：

同一份星图从哪里来，要能看出来
同一内容被重复执行，要能去重和对账
断线恢复、重放和日志回看时，要能定位原始来源

日志和事件里应该体现：

来源类型
来源标识
是否命中缓存
内容摘要或可比对指纹
内容体量

但不要直接暴露：

敏感鉴权材料
敏感查询参数
过长的原始正文

兼容与迁移

建议分三阶段迁移。

阶段 1

先把批跑执行器从“吃路径”改成“吃统一来源”。

命令行仍然只用本地兼容来源
内部先统一收敛
不改变外部日常用法

阶段 2

再增加本机非文件来源。

标准输入
内联文本
订阅链路中的来源列表

这一阶段先把本地和长链路入口打通，不急着引入网络来源。

阶段 3

最后增加远端来源、平台制品、缓存、鉴权和来源审计。

服务调用可以直接提交来源列表
长链路任务下发可以传可追踪来源
批跑执行和恢复链路共享同一套来源标识

测试建议

完整版里必须补回归测试，否则很容易把现有本地文件用法弄坏。

至少应覆盖：

本地兼容来源正常读取
本地兼容来源不存在
标准输入正常读取
内联文本正常读取
远端来源正常拉取
远端来源超时、鉴权失败、未找到、内容过大
缓存命中与失效
任务下发只带文本、只带来源、两者并存时的优先级
现有批跑入口在兼容场景下保持稳定
恢复链路中的重复任务不会被重复执行

实现切分建议

建议把这轮改造切成几块独立工作：

1. 来源模型与解析层

先定义统一来源抽象
先支持本地兼容来源

2. 批跑执行器适配

批跑入口改为消费统一来源
执行期不再直接感知“路径就是全部输入语义”

3. 本机非文件来源

增加标准输入和内联文本
保证本地闭环稳定

4. 长链路来源语义

统一文本任务与来源列表的优先级
保证断线恢复和回放语义不漂移

5. 远端来源能力

独立实现
独立测试
不与基础执行器重构混在同一次提交里

最终结论

这轮改造不该被理解为“让外部也能传本机路径”，而应该被理解为：

统一 code 的输入语义
让命令行、交互、服务调用和长链路都基于同一个来源抽象
把本机路径降级为一种兼容来源

建议最终稳定口径：

本机路径是兼容方式，不是正式协议主语义
来源列表才是 code 的长期正式输入模型
内联内容是外部调用的默认推荐路径
远端来源和平台制品是平台化扩展路径