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
+12
View File
@@ -1,3 +1,4 @@
// 画布 AI 的私有 IPC 客户端与模型目录:平台侧只看到稳定模型 ID,执行后端保留在 worker 内。
package codex
import (
@@ -15,8 +16,10 @@ import (
"time"
)
// CanvasInputLimit 限制提示词字节数;图片另按解码后的总字节限制。
const CanvasInputLimit = 1 << 20
// CanvasModel 是过滤后的模型能力快照;Backend 不序列化,仅供 worker 启动 CLI。
type CanvasModel struct {
ID string `json:"id"`
Label string `json:"label"`
@@ -32,6 +35,7 @@ type CanvasModel struct {
// Only curated catalog fields leave the worker. Raw CLI cache metadata,
// local paths, authentication files and backend configuration stay private.
// workerCanvasModels 读取 worker 本地缓存,只公布 list 可见且支持文本/图像输入的条目。
func workerCanvasModels() ([]CanvasModel, error) {
raw, err := os.ReadFile("/home/node/.codex/models_cache.json")
if err != nil {
@@ -53,6 +57,7 @@ func workerCanvasModels() ([]CanvasModel, error) {
if entry.Visibility != "list" || entry.Slug == "" || strings.HasPrefix(entry.Slug, "-") || len(entry.Slug) > 128 {
continue
}
// 稳定散列生成公开 ID;标签可展示,实际 slug 不作为公开 Backend 字段输出。
sum := sha256.Sum256([]byte("codex-cli/" + entry.Slug))
inputs := []string{}
for _, value := range entry.Inputs {
@@ -72,6 +77,7 @@ func workerCanvasModels() ([]CanvasModel, error) {
}
result = append(result, CanvasModel{ID: "codex-" + hex.EncodeToString(sum[:16]), Label: label, Provider: "codex-cli", InputModalities: inputs, OutputModalities: []string{"text"}, Available: true, MaxExecutionMS: 90000, MaxInputBytes: CanvasInputLimit, ParametersSchema: map[string]any{"type": "object", "properties": map[string]any{}, "additionalProperties": false}, Backend: entry.Slug})
}
// 图片输出能力必须显式列入已验证后端名单,不能根据支持图片输入推断支持图片生成。
verified := map[string]bool{}
for _, id := range strings.Split(os.Getenv("FOUNDRY_CANVAS_IMAGE_MODELS"), ",") {
id = strings.TrimSpace(id)
@@ -95,8 +101,10 @@ func workerCanvasModels() ([]CanvasModel, error) {
return result, nil
}
// CanvasClient 通过固定 Unix socket 发送 HTTP;URL 主机名只是协议占位符,不进行 DNS 连接。
type CanvasClient struct{ client *http.Client }
// NewCanvasClient 在未配置 socket 时返回 nil,调用方法会转换为明确的不可用错误。
func NewCanvasClient(socket string) *CanvasClient {
if socket == "" {
return nil
@@ -106,6 +114,8 @@ func NewCanvasClient(socket string) *CanvasClient {
}}
return &CanvasClient{client: &http.Client{Transport: transport, Timeout: 182 * time.Second, CheckRedirect: func(*http.Request, []*http.Request) error { return http.ErrUseLastResponse }}}
}
// Models 限制目录响应为 256 KiB,只接受成功状态和完整 JSON,隐藏 worker 内部失败原因。
func (c *CanvasClient) Models(ctx context.Context) ([]CanvasModel, error) {
if c == nil {
return nil, errors.New("codex_unavailable")
@@ -135,6 +145,7 @@ func (c *CanvasClient) Models(ctx context.Context) ([]CanvasModel, error) {
return result.Models, nil
}
// CanvasTask 在 platform 调度器与 worker 之间传递提示、模型及可选图片;当前参数对象必须为空。
type CanvasTask struct {
OutputModality string `json:"output_modality,omitempty"`
Images []CanvasImage `json:"images,omitempty"`
@@ -143,6 +154,7 @@ type CanvasTask struct {
Parameters map[string]any `json:"parameters"`
}
// Generate 是只需文本的兼容入口;复用结构化输出校验,并拒绝图片结果。
func (c *CanvasClient) Generate(ctx context.Context, input CanvasTask) (string, error) {
output, err := c.GenerateOutput(ctx, input)
if err != nil {
+8
View File
@@ -1,3 +1,4 @@
// 画布生成的结构化 IPC 输出;图片以字节传到核心,再由平台资产流程验证和持久化。
package codex
import (
@@ -9,13 +10,17 @@ import (
"net/http"
)
// CanvasImageBytesLimit 限制原始图片总字节,响应上限另为 JSON/base64 编码留出空间。
const CanvasImageBytesLimit = 20 << 20
const canvasArtifactResponseLimit = 32 << 20
// CanvasImage 的 Data 在 JSON 中编码为 base64,仅用于私有 Unix 通道。
type CanvasImage struct {
MIME string `json:"mime_type"`
Data []byte `json:"data"`
}
// CanvasOutput 用 Kind 区分文本和图片,由 GenerateOutput 再校验形态与请求模态相符。
type CanvasOutput struct {
Kind string `json:"kind"`
Text string `json:"text,omitempty"`
@@ -24,6 +29,7 @@ type CanvasOutput struct {
// Encoded image bytes exist only on the private Unix IPC channel. Public Canvas
// jobs expose stable asset IDs/URLs and never serialize these bytes to browsers.
// GenerateOutput 先检查输入预算,再发送 IPC;映射稳定错误码,兼容旧 worker 的 result 文本字段。
func (c *CanvasClient) GenerateOutput(ctx context.Context, input CanvasTask) (CanvasOutput, error) {
if c == nil {
return CanvasOutput{}, errors.New("codex_unavailable")
@@ -51,6 +57,7 @@ func (c *CanvasClient) GenerateOutput(ctx context.Context, input CanvasTask) (Ca
return CanvasOutput{}, err
}
defer response.Body.Close()
// 多读一字节区分刚好达到上限与实际超限,防止截断响应被当成成功结果。
raw, err = io.ReadAll(io.LimitReader(response.Body, canvasArtifactResponseLimit+1))
if err != nil || len(raw) > canvasArtifactResponseLimit {
return CanvasOutput{}, errors.New("generation_failed")
@@ -80,6 +87,7 @@ func (c *CanvasClient) GenerateOutput(ctx context.Context, input CanvasTask) (Ca
return CanvasOutput{}, errors.New("generation_failed")
}
}
// 旧响应只允许回退到文本;图片请求缺少结构化图片时必须失败。
if result.Output == nil {
if input.OutputModality == "image" {
return CanvasOutput{}, errors.New("generation_failed")
+4
View File
@@ -1,3 +1,4 @@
// 本文件用临时目录和固定事件验证产物隔离及完成判定,不启动 CLI 或真实模型。
package codex
import (
@@ -7,6 +8,7 @@ import (
"testing"
)
// TestCanvasArtifactDirectoryIsolation 拒绝目录外图片、多张图片和软链接,只接收生成目录内唯一图片。
func TestCanvasArtifactDirectoryIsolation(t *testing.T) {
root := t.TempDir()
generated := filepath.Join(root, "generated_images")
@@ -48,6 +50,8 @@ func TestCanvasArtifactDirectoryIsolation(t *testing.T) {
t.Fatal("symlink escaped job output directory")
}
}
// TestCanvasAgentCompletionRequiresSuccessfulTurn 拒绝仅有部分文本或完成后报错的流,接受成功结束的流。
func TestCanvasAgentCompletionRequiresSuccessfulTurn(t *testing.T) {
if _, ok := canvasAgentText([]byte("{\"type\":\"item.completed\",\"item\":{\"type\":\"agent_message\",\"text\":\"partial\"}}\n")); ok {
t.Fatal("partial generation accepted")
+12
View File
@@ -1,3 +1,4 @@
// worker 侧画布执行:每次任务新建临时 CODEX_HOME,按模态启动 CLI 并提取完成结果。
package codex
import (
@@ -16,6 +17,7 @@ import (
"time"
)
// executeCanvasTask 由共享执行槽保护;模型已从目录选出,但仍须核对请求模态和输入图片。
func executeCanvasTask(w http.ResponseWriter, r *http.Request, input CanvasTask, model CanvasModel) {
imageOutput := input.OutputModality == "image"
if input.OutputModality != "" && input.OutputModality != "text" && !imageOutput {
@@ -32,6 +34,7 @@ func executeCanvasTask(w http.ResponseWriter, r *http.Request, input CanvasTask,
}
ctx, cancel := context.WithTimeout(r.Context(), duration)
defer cancel()
// 临时目录承载认证软链接、输入图片和生成产物;成功与所有失败路径都由 defer 删除。
job, err := os.MkdirTemp("", "foundry-canvas-")
if err != nil {
fail(w, 503, "codex_unavailable")
@@ -43,11 +46,13 @@ func executeCanvasTask(w http.ResponseWriter, r *http.Request, input CanvasTask,
fail(w, 503, "codex_unavailable")
return
}
// 关闭 shell、应用、插件等能力;文本模型还关闭图片生成,画布模式忽略用户配置与规则。
args := []string{"--ask-for-approval", "never", "--disable", "shell_tool", "--disable", "apps", "--disable", "plugins", "--disable", "multi_agent", "--disable", "hooks", "--disable", "memories", "-c", `web_search="disabled"`}
if !imageOutput {
args = append(args, "--disable", "image_generation")
}
args = append(args, "exec", "--json", "--sandbox", "read-only", "--skip-git-repo-check", "--ephemeral", "--ignore-user-config", "--ignore-rules", "--model", model.Backend)
// 对图片内容嗅探 MIME,而非仅信任传入类型;只允许已知栅格格式并限制总大小。
total := 0
for i, image := range input.Images {
total += len(image.Data)
@@ -80,6 +85,7 @@ func executeCanvasTask(w http.ResponseWriter, r *http.Request, input CanvasTask,
cmd.Dir = "/work"
cmd.Env = []string{"PATH=/usr/local/bin:/usr/bin:/bin", "HOME=/home/node", "CODEX_HOME=" + home, "SSL_CERT_FILE=/etc/ssl/certs/ca-certificates.crt"}
cmd.Stdin = strings.NewReader(prompt)
// 独立进程组使请求取消/超时可杀掉 CLI 及其子进程,避免残留后台任务。
cmd.SysProcAttr = &syscall.SysProcAttr{Setpgid: true}
cmd.Cancel = func() error {
err := syscall.Kill(-cmd.Process.Pid, syscall.SIGKILL)
@@ -103,6 +109,7 @@ func executeCanvasTask(w http.ResponseWriter, r *http.Request, input CanvasTask,
fail(w, 502, "generation_failed")
return
}
// CLI 退出零还不够:事件流必须完成且无错误,图片结果还需从专用产物目录读取。
text, completed := canvasAgentText(output.buffer.Bytes())
if !completed {
fail(w, 502, "generation_failed")
@@ -122,6 +129,8 @@ func executeCanvasTask(w http.ResponseWriter, r *http.Request, input CanvasTask,
}
writeJSON(w, 200, map[string]any{"output": result})
}
// canvasAgentText 逐行读取 JSON 事件,保留最后一条 agent_message;任何坏行或失败事件均拒绝。
func canvasAgentText(raw []byte) (string, bool) {
result := ""
completed := false
@@ -148,6 +157,9 @@ func canvasAgentText(raw []byte) (string, bool) {
}
return result, completed
}
// readCanvasGeneratedImage 只遍历本次 generated_images,拒绝软链接、非常规文件和多张候选图片。
// 此处只做格式嗅探与字节限制;完整解码和尺寸验证由平台资产接收流程负责。
func readCanvasGeneratedImage(root string) (*CanvasImage, error) {
var result *CanvasImage
err := filepath.WalkDir(root, func(path string, entry fs.DirEntry, walkErr error) error {
+10
View File
@@ -1,3 +1,4 @@
// 公开文本生成代理:用项目专属凭据授权后,把受限任务通过 Unix IPC 转发给 worker。
package codex
import (
@@ -16,16 +17,19 @@ import (
"time"
)
// 公开请求 32 KiB、返回 512 KiB;worker 执行期限九十秒,IPC 客户端另留两秒收尾。
const (
maxRequest = 32 << 10
maxOutput = 512 << 10
timeout = 90 * time.Second
)
// task 仅允许 prompt,公开调用方不能传 sandbox、工具配置或可执行参数。
type task struct {
Prompt string `json:"prompt"`
}
// writeJSON 统一输出 JSON 并禁用缓存,内部调用者须在此之前完成状态码选择。
func writeJSON(w http.ResponseWriter, status int, value any) {
w.Header().Set("Content-Type", "application/json")
w.Header().Set("Cache-Control", "no-store")
@@ -33,10 +37,12 @@ func writeJSON(w http.ResponseWriter, status int, value any) {
_ = json.NewEncoder(w).Encode(value)
}
// fail 将依赖或授权失败转换为稳定错误码,避免向公开 API 泄露本地路径和配置。
func fail(w http.ResponseWriter, status int, code string) {
writeJSON(w, status, map[string]string{"error": code})
}
// readTask 限制 JSON 大小、未知字段、尾随值与空白 prompt;失败时已写响应。
func readTask(w http.ResponseWriter, r *http.Request, limit int64) (task, bool) {
var input task
decoder := json.NewDecoder(http.MaxBytesReader(w, r.Body, limit))
@@ -59,6 +65,7 @@ func readTask(w http.ResponseWriter, r *http.Request, limit int64) (task, bool)
// Register enables the public endpoint only when both configuration files are supplied.
// Each credential digest belongs to exactly one project.
// Register 在两项配置齐备时挂载路由,凭据文件每次请求重新读取以支持撤销。
func Register(mux *http.ServeMux, projects map[string]string, socket, grantsFile string) error {
if socket == "" && grantsFile == "" {
return nil
@@ -91,6 +98,7 @@ func Register(mux *http.ServeMux, projects map[string]string, socket, grantsFile
fail(w, 503, "codex_unavailable")
return
}
// 凭据是 32 字节十六进制值;将摘要与授权表恒定时间比较,再核对目标项目作用域。
hash := sha256.Sum256(key)
var scope string
for digest, project := range grants {
@@ -113,6 +121,7 @@ func Register(mux *http.ServeMux, projects map[string]string, socket, grantsFile
if !ok {
return
}
// IPC 只发送解析后的任务体,不转发公开 Authorization 头;连接目的地固定为配置的 socket。
body, _ := json.Marshal(input)
req, err := http.NewRequestWithContext(r.Context(), http.MethodPost, "http://codex/exec", bytes.NewReader(body))
if err != nil {
@@ -129,6 +138,7 @@ func Register(mux *http.ServeMux, projects map[string]string, socket, grantsFile
return
}
defer resp.Body.Close()
// worker 响应必须在预算内且为合法 JSON;保留其状态与 Retry-After,隐藏传输错误细节。
data, err = io.ReadAll(io.LimitReader(resp.Body, maxOutput+1))
if err != nil || len(data) > maxOutput || !json.Valid(data) {
fail(w, 502, "invalid_codex_response")
+3
View File
@@ -1,3 +1,4 @@
// 公开代理回归使用临时 Unix socket 假 worker,不访问外部服务或真实 CLI。
package codex
import (
@@ -13,6 +14,7 @@ import (
"testing"
)
// TestProjectAuthorizationAndForwarding 检查缺凭据/跨项目拒绝、严格任务体、大小限制及授权文件即时撤销。
func TestProjectAuthorizationAndForwarding(t *testing.T) {
dir := t.TempDir()
socket := filepath.Join(dir, "worker.sock")
@@ -20,6 +22,7 @@ func TestProjectAuthorizationAndForwarding(t *testing.T) {
if err != nil {
t.Fatal(err)
}
// 假 worker 要求代理已移除 Authorization,只回显 prompt,用于确认最小化转发契约。
worker := &http.Server{Handler: http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
if r.URL.Path != "/exec" || r.Header.Get("Authorization") != "" {
fail(w, 500, "unexpected_worker_request")
+12
View File
@@ -1,3 +1,4 @@
// Package codex 在核心 API 与受限 CLI worker 间通过 Unix socket 通信,隔离公开凭据与本地执行环境。
package codex
import (
@@ -15,16 +16,19 @@ import (
"time"
)
// executable 指向部署容器预装 CLI,不从请求或 PATH 选择可执行文件。
const executable = "/opt/codex/node_modules/.bin/codex"
var errOutputLimit = errors.New("Codex output limit exceeded")
// outputBuffer 对 CLI stdout 累计限额;超限标记用于进程结束后选择稳定错误响应。
type outputBuffer struct {
buffer bytes.Buffer
exceeded bool
limit int
}
// Write 实现 io.Writer,默认使用公共输出限制,画布事件流可另设更大内部预算。
func (b *outputBuffer) Write(p []byte) (int, error) {
limit := b.limit
if limit == 0 {
@@ -37,6 +41,7 @@ func (b *outputBuffer) Write(p []byte) (int, error) {
return b.buffer.Write(p)
}
// ServeWorker 由 main 的 codex-worker 模式调用,重建 0600 socket,只允许一个生成任务同时执行。
func ServeWorker(socket string) error {
syscall.Umask(0077)
if err := os.Remove(socket); err != nil && !errors.Is(err, os.ErrNotExist) {
@@ -50,6 +55,7 @@ func ServeWorker(socket string) error {
if err := os.Chmod(socket, 0600); err != nil {
return err
}
// 文本 /exec 与 /canvas/exec 共享一个槽位;忙时立即 429,目录读取不占执行槽。
slot := make(chan struct{}, 1)
mux := http.NewServeMux()
mux.HandleFunc("POST /exec", func(w http.ResponseWriter, r *http.Request) {
@@ -87,6 +93,7 @@ func ServeWorker(socket string) error {
fail(w, 503, "codex_unavailable")
return
}
// 仅按公开 ID 匹配当前目录,再在 worker 内取 Backend,调用方不能任意指定 CLI 模型名。
var selected *CanvasModel
for _, model := range models {
if model.ID == input.ModelID {
@@ -112,7 +119,10 @@ func ServeWorker(socket string) error {
return server.Serve(listener)
}
// execute 为旧文本入口保留默认模型选择,实际进程生命周期集中在 executeModel。
func execute(w http.ResponseWriter, r *http.Request, prompt string) { executeModel(w, r, prompt, "") }
// executeModel 用请求期限约束 CLI,禁用外部工具能力;失败仅公开错误码,不转发 stderr。
func executeModel(w http.ResponseWriter, r *http.Request, prompt, model string) {
ctx, cancel := context.WithTimeout(r.Context(), timeout)
defer cancel()
@@ -126,6 +136,7 @@ func executeModel(w http.ResponseWriter, r *http.Request, prompt, model string)
cmd.Dir = "/work"
cmd.Env = []string{"PATH=/usr/local/bin:/usr/bin:/bin", "HOME=/home/node", "CODEX_HOME=/home/node/.codex", "SSL_CERT_FILE=/etc/ssl/certs/ca-certificates.crt"}
cmd.Stdin = strings.NewReader(prompt)
// Setpgid 配合负 PID kill 终止整个进程组;WaitDelay 约束取消后的输出管道等待。
cmd.SysProcAttr = &syscall.SysProcAttr{Setpgid: true}
cmd.Cancel = func() error {
err := syscall.Kill(-cmd.Process.Pid, syscall.SIGKILL)
@@ -146,6 +157,7 @@ func executeModel(w http.ResponseWriter, r *http.Request, prompt, model string)
case err != nil:
fail(w, 502, "codex_failed")
default:
// 只有合法事件流、成功结束事件及非空最终文本才能作为公开生成结果返回。
var result string
var completed bool
for _, line := range bytes.Split(bytes.TrimSpace(output.buffer.Bytes()), []byte("\n")) {