docs: annotate Foundry source and deployment lifecycle in Chinese [skip ci]

This commit is contained in:
2026-11-16 17:52:11 +08:00
parent 30829eeb86
commit 1090591503
123 changed files with 1279 additions and 3 deletions
+15
View File
@@ -1,3 +1,4 @@
// AI 步骤开始/完成的事务边界:执行前与回写前分别校验权限、租约和目标身份,防止迟到输出覆盖新状态。
package platform
import (
@@ -8,6 +9,8 @@ import (
"gitea.entroia.com/Zayden-Jung/foundry-core/internal/codex"
)
// startCanvasStep 持工作区锁解析目标当前 owner,再检查租约、编辑权限与内容指纹,成功才将 queued 改 running。
// 不可执行时先释放事务,再调用完成流程记录拒绝状态,避免嵌套事务互锁。
func (s *service) startCanvasStep(ctx context.Context, run canvasQueueRun, step canvasAIStepPlan) (bool, error) {
tx, err := s.db.BeginTx(ctx, nil)
if err != nil {
@@ -78,9 +81,13 @@ func (s *service) startCanvasStep(ctx context.Context, run canvasQueueRun, step
}
return true, nil
}
// finishCanvasStep 是文本/无输出失败路径的兼容包装,所有落库与事件逻辑集中在结构化完成函数。
func (s *service) finishCanvasStep(ctx context.Context, run canvasQueueRun, step canvasAIStepPlan, text, code string, started bool) (string, error) {
return s.finishCanvasStepOutput(ctx, run, step, codex.CanvasOutput{Kind: "text", Text: text}, code, started)
}
// finishCanvasStepOutput 在同一事务中保存输出、条件应用、步骤终态与事件;已终态或租约失效则直接保留旧结果。
func (s *service) finishCanvasStepOutput(ctx context.Context, run canvasQueueRun, step canvasAIStepPlan, generated codex.CanvasOutput, code string, started bool) (string, error) {
tx, err := s.db.BeginTx(ctx, nil)
if err != nil {
@@ -104,12 +111,14 @@ func (s *service) finishCanvasStepOutput(ctx context.Context, run canvasQueueRun
if err != nil {
return "", err
}
// 取消、删除失效和其他完成者已写出的终态优先,迟到 worker 结果不得改回成功。
if oldStatus != "queued" && oldStatus != "running" {
return oldStatus, nil
}
if runStatus != "running" || !lease.Valid || lease.String != run.Lease {
return oldStatus, nil
}
// 统一映射依赖失败、内容冲突、取消与生成错误,run.cancel_requested 优先于局部生成结果。
status := "succeeded"
switch code {
case "dependency_failed":
@@ -139,6 +148,7 @@ func (s *service) finishCanvasStepOutput(ctx context.Context, run canvasQueueRun
var appliedEvent response
var output any
var version any
// 生成成功才保存可供恢复的输出;内容指纹冲突时仍保留 output,但不覆盖当前节点。
if code == "" && started {
var outputID string
err = tx.QueryRowContext(ctx, `SELECT gen_random_uuid()::text`).Scan(&outputID)
@@ -177,6 +187,7 @@ func (s *service) finishCanvasStepOutput(ctx context.Context, run canvasQueueRun
return "", err
}
}
// 仍使用原计划来源构造指纹,owner 变化由 canonical 稳定身份单独解析,拖动不造成假冲突。
if !identityOK || target == nil || canvasTargetFingerprint(step.BoardID, step.NodeID, target) != step.Fingerprint {
status, code = "conflict", "target_changed"
} else {
@@ -199,6 +210,7 @@ func (s *service) finishCanvasStepOutput(ctx context.Context, run canvasQueueRun
}
}
}
// output 与 applied 是不同事件;换 owner 后的冲突附完整模型,客户端可定位当前显式应用目标。
if output != nil {
event := response{"step_id": step.ID, "board_id": eventBoard, "origin_board_id": step.BoardID, "canonical_root": step.CanonicalRoot, "target_incarnation": step.TargetIncarnation, "node_id": step.NodeID, "output": output}
if status == "conflict" && identityOK && step.CanonicalRoot != "" && eventBoard != step.BoardID {
@@ -249,6 +261,9 @@ func (s *service) finishCanvasStepOutput(ctx context.Context, run canvasQueueRun
}
return status, nil
}
// completeCanvasRun 从数据库步骤聚合实际终态而非信任内存 results;仍有活跃步骤则不提前结束 run。
// 仅当前租约可清空租约并写 run.completed,兼容部分成功、全冲突和取消。
func (s *service) completeCanvasRun(ctx context.Context, run canvasQueueRun, _ map[string]canvasStepResult) error {
tx, err := s.db.BeginTx(ctx, nil)
if err != nil {