Documentation
¶
Overview ¶
Package run 定义运行记录实体：一次 workflow 执行的不可变历史。
落盘为三份文件（见 spec〈落盘存储结构〉）：run.json（Record）、trace.jsonl（每行一条 TraceEntry）、run-summary.md（RenderSummary 渲染）。持久化由 internal/store 负责，本包只管类型 与纯逻辑（状态派生、总结渲染）。
Index ¶
- Variables
- func LastUnsuccessfulStepIndex(trace []TraceEntry) *int
- func ProcessAlive(pid int) bool
- func ProcessStartToken(pid int) (string, bool)
- func ProgressCount(trace []TraceEntry) int
- func RenderSummary(record *Record, trace []TraceEntry) string
- func StopProcess(pid int) error
- func ValidateID(id string) error
- func ValidateWorkingDir(absDir string) error
- type Record
- type Status
- type TraceEntry
Constants ¶
This section is empty.
Variables ¶
var ( // ErrWorkingDirNotExist 表示目标工作目录不存在。 ErrWorkingDirNotExist = errors.New("工作目录不存在") // ErrWorkingDirNotDir 表示目标路径存在但不是目录。 ErrWorkingDirNotDir = errors.New("工作目录不是目录") )
Functions ¶
func LastUnsuccessfulStepIndex ¶ added in v0.0.2
func LastUnsuccessfulStepIndex(trace []TraceEntry) *int
LastUnsuccessfulStepIndex 返回 trace 中最后一条失败记录的 stepIndex。run.json 不保存失败步；需要展示失败位置时 从 trace 推断。没有失败记录时返回 nil。
func ProcessAlive ¶
ProcessAlive 报告某 pid 的进程是否存活（signal 0 探测：不投递信号、只做存在性/权限检查）。 ESRCH → 已死；EPERM → 存在但属他人（视为存活）；nil → 存活。
func ProcessStartToken ¶
ProcessStartToken 暴露给编排器在创建运行时捕获**自身**进程的启动时刻标识，随 run.json 落盘； 与 processAlive 用同一来源，保证同一进程存续期内比对必然相等。不支持平台/读不到返回 ("", false)。
func ProgressCount ¶ added in v0.0.2
func ProgressCount(trace []TraceEntry) int
ProgressCount 返回进度分子 k = trace 中「唯一 stepIndex 且（最后一次记录）success」的步数。 与「数物理行」不同：resume 会保留失败行 + 续写补跑行，同一 stepIndex 有多条，数行数会让 k 越过 分母 N（如 11/10）。按 stepIndex 去重、以每步最后一次记录（＝执行序最新）为准，保证 k ≤ N 恒成立。 审计视角要看全部历史记录仍走 run show --trace（不去重）。
func RenderSummary ¶
func RenderSummary(record *Record, trace []TraceEntry) string
RenderSummary 把一次运行渲染成 run-summary.md（给人 / AI 阅读的报告，机器读 run.json）。 结构见 spec〈落盘存储结构〉：头部 + 需求 + 状态耗时 + 工作目录 + 步骤表 + XML 包裹的逐节点产物。 trace 提供逐步结果，record.Artifacts 提供各节点最终产物。
func StopProcess ¶
StopProcess 终止一次运行的进程。先按进程组发 SIGTERM（kill(-pid) 连带引擎子进程一并收）， 组不存在时回退为向单进程发 SIGTERM：
- ESRCH：pid 不是组长（例如终端管道 `cat req | conduct workflow run` 里 conduct 未 Setsid）， 没有 id==pid 的进程组可投递 → 回退 kill(pid, SIGTERM) 只终止 conduct 本身；
- 其余错误（如 EPERM 属他人进程）：原样上抛，不吞。
只有 UI self-exec 路径以 Setsid 独立成组时，组信号才真正连带引擎子进程整组退出；终端/管道启动 退化为仅终止 conduct 进程本身——当前步的引擎子进程遗留到本步自然结束、编排器已死不再驱动下一步， 属可接受降级。进程停写后由 pid 判活派生 interrupted，不引入新落盘状态。
func ValidateID ¶
ValidateID 校验 run id 合法（防路径穿越）：只允许 [A-Za-z0-9._-]，且不为 . / ..。
func ValidateWorkingDir ¶
ValidateWorkingDir 校验一个（应为绝对路径的）工作目录已存在且确为目录。 不存在 → ErrWorkingDirNotExist；存在但非目录 → ErrWorkingDirNotDir；其余 stat 错误如实带出。 校验通过返回 nil。调用方负责先把用户输入转为绝对路径（filepath.Abs）。
Types ¶
type Record ¶
type Record struct {
ID string `json:"id"`
Workflow string `json:"workflow"`
WorkflowSnapshot *workflow.Definition `json:"workflowSnapshot"`
UserPrompt string `json:"userPrompt"`
Cwd string `json:"cwd"`
Status Status `json:"status"`
Pid int `json:"pid"`
PidStartTime string `json:"pidStartTime,omitempty"` // 进程启动时刻标识，防 pid 复用误判/误杀；旧记录/不支持平台为空
Steps int `json:"steps"`
StartedAt string `json:"startedAt"`
EndedAt *string `json:"endedAt"`
Artifacts map[string]string `json:"artifacts"`
Error *string `json:"error"`
}
Record 是 run.json 的结构——运行概要 + 开始那一刻冻结的 workflow 快照，使这次运行永远可复现。 endedAt / error 用指针，未终结时显式序列化为 null（对齐 spec 示例）。
func (*Record) EffectiveStatus ¶
EffectiveStatus 返回对外展示的状态：running 且进程已死 → interrupted，其余照 Status。
type TraceEntry ¶
type TraceEntry struct {
StepIndex int `json:"stepIndex"`
Type string `json:"type"` // agent | evaluator
NodeID string `json:"nodeId"`
DisplayName string `json:"displayName"`
Iteration int `json:"iteration"`
Engine string `json:"engine"`
EngineConfig *workflow.EngineConfig `json:"engineConfig,omitempty"`
Input string `json:"input"`
Success bool `json:"success"`
Error *string `json:"error"`
Output string `json:"output"`
Tokens int `json:"tokens,omitempty"`
SessionID string `json:"sessionId,omitempty"` // 选填：该步引擎的会话/线程 id（引擎回报则记），凭它回放本步
DurationMs int64 `json:"durationMs"`
}
TraceEntry 是 trace.jsonl 的一行——单个执行步骤的完整记录（自解释，不依赖当时的定义）。
func (TraceEntry) StepLabel ¶
func (e TraceEntry) StepLabel() string
StepLabel 返回一步在报告/列表里的展示名：evaluator 步加「· 评测」后缀，与 agent 步区分 （否则带 evaluator 的节点会产出多行同名步骤，分不清写与评）。
Source Files