boos/BoosAPI
2
0
Fork 2
Code Issues Pull Requests Packages Projects Releases Wiki Activity

Compare commits

base: boos/BoosAPI:888563a22bedb97d49df7eb3be0e609f90626ca1
Branches Tags
boos/BoosAPI:feat/embed-desktop boos/BoosAPI:main boos/BoosAPI:refactor/rust-backend boos/BoosAPI:nit_edu
..
compare: boos/BoosAPI:refactor/rust-backend
Branches Tags
boos/BoosAPI:feat/embed-desktop boos/BoosAPI:main boos/BoosAPI:refactor/rust-backend boos/BoosAPI:nit_edu

922 Commits
888563a22b .. refactor/rust-backend

Author SHA1 Message Date
boos c3327b9ef6 fix(agent): classify run/terminal/spawn tools as Execute risk 
classify_tool_risk missed execute-class tools whose names use "run",
"terminal", "spawn" or "process" rather than bash/shell/exec/command — most
notably "RunInTerminal". Such a tool fell through to ReadOnly and would
therefore auto-allow without approval in Default/AcceptEdits mode, a real gap
in the permission gate. Broaden the Execute branch to catch them; over-
classifying as Execute only ever asks for more approval, so it is fail-safe.

This was already asserted by an existing unit test (classifies_execute_tools
expects RunInTerminal -> Execute); the test only became runnable after the
rebase onto refactor/rust-backend pulled in the AppConfig test-fixture repair
that had been blocking the lib test binary. Full agent_workbench unit suite
now 32/32; the four integration suites stay green.
 2026-06-22 10:53:45 +08:00
boos d751055452 test(agent): pin the TOCTOU mitigation property for file tools 
The file tools (Read/Write/Edit) open paths inside the SDK process after the
can_use_tool callback validates them, leaving a check-vs-open window. Fully
closing it atomically needs openat2(RESOLVE_BENEATH) file tools replacing the
SDK's in-process ones (tracked as follow-up; the Edit tool's file-state-cache
contract makes that a non-trivial reimplementation).

This test pins the fact that makes the window unreachable under the current
model: an exploit needs a concurrent mutator, the only agent-controlled source
of concurrency is a backgrounded process, and bwrap's PID namespace
(--unshare-all) makes the bash command PID 1 — so the kernel reaps any
backgrounded job when the single bash call exits. The test backgrounds a writer
that would keep appending for ~2s and asserts its output stops the moment the
call returns. With sequential tool execution and per-session bind isolation,
no surviving concurrent mutator exists to win the race.

This is an honest mitigation with evidence, not a claim that the in-process
open is atomic.
 2026-06-22 10:53:45 +08:00
boos b0ce83a937 feat(agent): confine agent bash in an OS sandbox (bubblewrap), mode-gated 
The SDK's built-in Bash tool ran commands as a bare subprocess with only
current_dir set — no OS boundary. On a server that let an agent shell read
/etc/shadow, cd /, write anywhere the process uid could, and reach the
network; the phase-1 path validation only guards the file tools, not bash.
(The SDK's SandboxSettings is dead config: Agent::new never reads it.)

Replace it with SandboxedBashTool — same name and input schema, registered
via custom_tools so it overrides the built-in by name — that confines the
command with bubblewrap, gated by permission mode:

- Default / AcceptEdits (review modes): run inside a bwrap namespace with the
  system mounted read-only, the session sandbox dir bind-mounted rw at its
  real path and made the cwd, /etc //root //home and all other host paths
  absent, and --unshare-all (network included). Filesystem escape and network
  egress are blocked by the kernel, not by convention.
- FullAccess (explicitly dangerous): unconfined, same as before, but every
  command is audit-logged with a warning.

Fail-closed: in a review mode, if bwrap is unavailable the command is refused
rather than silently run unconfined — no fabricated boundary.

Verified end-to-end in tests/agent_bash_sandbox.rs by invoking the tool:
under Default mode `cat /etc/passwd` sees no host passwd, `ls /` exposes no
etc//root//home, a write to /etc/cron.d/x fails (and the host file is never
created), and the network is unreachable; in-sandbox work succeeds and lands
in the real session dir; FullAccess can see the host. bwrap 0.11.2 confirmed
functional on this host (root, CAP_SYS_ADMIN, user namespaces enabled).
Phase-1 suites stay green.
 2026-06-22 10:53:45 +08:00
boos 3bb1272c6d fix(agent): prevent dangling-symlink write escape from the sandbox 
validate_path_within_cwd used exists() to decide whether a path was new.
exists() follows symlinks, so a *dangling* symlink (target missing) reported
false and fell into the not-yet-existing branch, which only bound-checked the
nearest existing ancestor — never the symlink itself. An approved
`ln -s /etc/cron.d/pwn evil` inside the sandbox would therefore pass
validation, and a subsequent Write to `evil` would follow the link and create
a file outside the sandbox. In AcceptEdits mode this chained cleanly: approve
one innocuous-looking symlink (Execute), then writes auto-allow.

Resolve every path component with lstat (symlink_metadata, which does not
follow links) instead of exists():
- Final component: if it is a symlink (dangling or live), resolve its real
  target via read_link + canonicalize-nearest-ancestor and reject unless the
  target stays within the sandbox.
- Ancestor walk: an intermediate dangling symlink directory is likewise
  resolved and bound-checked rather than skipped.

Live symlinks were already caught by canonicalize; this closes the dangling
case. It does not close the check-vs-open TOCTOU (the open happens inside the
SDK tool and would need O_NOFOLLOW/openat2 there); tracked for phase 2 along
with OS-level bash isolation.

Covered by tests/agent_sandbox.rs (dangling symlink to absolute and relative
targets, write tool through a dangling link, write through an intermediate
dangling symlink dir, all rejected; dangling link pointing inside and ordinary
new files still allowed) plus mirrored in-crate unit tests.
 2026-06-22 10:53:45 +08:00
boos 5501558354 fix(agent): make tool approval race-free with an atomic state machine 
The previous approval registry used a oneshot channel, so two independent
signals decided an approval: the HTTP handler's result (from Sender::send's
bool) and the agent loop's allow/deny (from which timeout arm fired). At the
300s boundary these could disagree — a late /approve could see send() return
Ok (receiver not yet dropped) and report ok:true to the user, while the
timeout's final poll simultaneously fired and denied the tool. The frontend
was told "approved" while nothing ran. The mirror case (ok:false but allowed)
was impossible, so it never executed an unapproved tool, but the user-facing
signal could lie.

Replace the channel with a single source of truth: each entry is an
AtomicU8 state machine (Pending -> Approved/Denied/TimedOut) plus a Notify.
The decision is made by exactly one compare_exchange from Pending — whoever
wins (approver or timeout) settles it, everyone else observes a losing CAS
and no-ops. resolve() now returns whether *its* CAS won, so /approve tells
the frontend the truth; the loop decides purely from the settled atomic.
They read the same atomic and cannot disagree.

A PendingGuard removes the registry entry on drop (normal completion or
aborted/disconnected session), so there is no leak on any path. The callback
also emits an approval_resolved SSE event with the final decision so a late
click — already told ok:false — can dismiss its modal with the real outcome.

Verified with an integration test that races resolve() against a near-zero
timeout 5000x and asserts ok==true iff the executed decision is Approved
(never a mixed state). Run via tests/ because the in-crate lib test binary
is currently blocked by unrelated AppConfig test fixtures in other modules.
 2026-06-22 10:53:45 +08:00
boos f0a76fd82c feat(agent): add Agent Workbench frontend panel 
A minimal chat UI for the server-side agent, wired to the SSE engine:

- Streams assistant text incrementally and renders each tool call as a card
  showing the tool name, input and (color-coded) output or denial reason.
- Surfaces interactive approval prompts: when the agent requests a risky
  tool, a modal shows the tool and its arguments and posts the user's
  decision to /api/agent/approve, unblocking the loop.
- Permission-mode selector (standard review / accept edits / full access),
  new-session control, and a live session usage bar (turns, tokens, cost).

Registered as /agent-workbench (admin) and /user/agent-workbench (user) in
the SPA router and sidebar. Typecheck and vite build pass.
 2026-06-22 10:53:45 +08:00
boos 2506713fad feat(agent): SSE agent route backed by open-agent-sdk via BoosAPI provider 
Adds the Agent Workbench HTTP surface wiring the open-agent-sdk loop into
BoosAPI:

- POST /api/agent/chat (SSE): runs an agentic turn and streams session /
  text / thinking / tool_use / tool_result / approval_request / result /
  error / done events. The agent's LLM calls are routed back through
  BoosAPI's own OpenAI-compatible /v1 using the built-in downstream key
  (constructed via the SDK's OpenAIProvider), so any aggregated model works
  and usage flows through the normal accounting pipeline.
- POST /api/agent/approve: resolves a pending tool approval by request id.
- GET /api/agent/status: engine info + a session's accounting.

Safety is enforced in the SDK permission callback: every tool first passes
sandbox path validation (no escaping the per-session working dir), then the
risk/mode matrix — writes and command execution require an interactive
approval round-trip (default mode) that blocks the loop until the user
answers or the request times out (300s -> deny). Each session runs in its
own data/agent_sessions/{id}/ sandbox and turn usage is persisted.

Registered in the API router and added open-agent-sdk as a path dependency.
 2026-06-22 10:53:45 +08:00
boos a060666f6f feat(agent): persist per-session token and cost accounting 
Adds the agent_sessions table (migration) and a session_store module that
owns its lifecycle:

- ensure_session: idempotently creates the session row on first chat.
- record_turn: accumulates input/output/total tokens, cost and turn count
  after each completed turn, bumping updated_at.
- get_session: user-scoped fetch so a tenant can only read its own session.

Backed by SQLite via SQLx, matching the existing service style. Unit-tested
against an in-memory database (idempotency, accumulation, user scoping).
 2026-06-22 10:53:45 +08:00
boos 4192798ceb feat(agent): add permission, sandbox and approval primitives for agent workbench 
Introduces the SDK-free building blocks for a server-side AI agent:

- permission: tool risk classification (ReadOnly/Write/Execute) and the
  per-mode decision matrix (Default/AcceptEdits/FullAccess). Default mode
  auto-allows reads and requires approval for writes/executes.
- sandbox: per-session isolated working directory under
  data/agent_sessions/{id}/ plus path validation that confines every tool
  path argument within the session directory (rejects ../, absolute and
  symlink escapes), mirroring the AQBot security model.
- approval: process-global registry bridging the SSE approval round-trip via
  oneshot channels, so the permission callback can block until the user
  approves or denies a risky tool.

All three modules are unit-tested in isolation (17 tests) and carry no
dependency on the agent SDK; the HTTP layer maps their results onto the
SDK permission callback in a later commit.
 2026-06-22 10:53:45 +08:00
boos 4a12610662 Merge remote-tracking branch 'origin/feat/comfy-cloud-adapter' into _merge_test 
# Conflicts:
#	src/routes/admin/compat.rs
#	src/routes/admin/downstream_keys.rs
#	src/routes/auth.rs
#	src/routes/comfyui/mod.rs
#	src/routes/comfyui_agent.rs
#	src/routes/events.rs
#	src/routes/money_printer.rs
#	src/routes/oauth.rs
#	src/routes/proxy/mod.rs
#	src/routes/video_agent_legacy.rs
 2026-06-22 10:14:52 +08:00
boos eddf3eff4e fix(deps): declare url crate so digital_human compiles 
digital_human.rs uses url::Url::parse but the crate was only a transitive
dependency, not declared in Cargo.toml, so the lib failed to compile with
E0433. Add the explicit dependency (url 2.x was already in Cargo.lock).
 2026-06-22 09:37:18 +08:00
boos 4d093548de feat(proxy): wire Gemini native v1beta endpoints through the conductor 
Implement the four Gemini native inbound endpoints so Gemini CLI / Google
GenAI SDKs can point their base URL at the gateway:

- GET  /v1beta/models — directory listing in Gemini shape, built from
  configured routes (like /v1/models); no upstream call, no billing.
- POST /v1beta/models/{model}:generateContent — non-streaming, routed
  through ProxyConductor with failover + usage_logs + billing.
- POST /v1beta/models/{model}:streamGenerateContent — SSE passthrough via
  open_stream_with_failover + sse_passthrough_response.
- POST /v1beta/models/{model}:countTokens — metadata call, routed for a
  channel but not billed.

Auth accepts the gateway key from ?key= or x-goog-api-key (Gemini
convention) and reuses the downstream-key authorization + limits.

Billing closes the loop: gemini_extract_usage reads usageMetadata
(promptTokenCount / candidatesTokenCount) for non-streaming, and
gemini_stream_usage_from_line feeds the shared StreamUsageAccumulator so
streamed usageMetadata is billed too.

Unit tests cover model:action parsing, usage extraction, the stream usage
parser, and query forwarding (key/alt dropped).
 2026-06-22 08:39:38 +08:00
boos aaa593ac31 feat(proxy): add Gemini native upstream executors 
Add Gemini-shaped upstream calls that mirror AQBot's native passthrough
and BoosAPI's /v1/responses forwarding: the model lives in the URL path
(/v1beta/models/{model}:{op}) and the key in ?key=, so the body is sent
verbatim with no model rewrite.

- gemini_base_url / gemini_operation_url normalize the v1beta root and
  build {base}/v1beta/models/{model}:{op}?key=...&{extra}, stripping a
  leading models/ prefix and handling the no-key case.
- execute_gemini_operation runs non-streaming ops (generateContent /
  countTokens) and returns upstream JSON verbatim.
- execute_gemini_stream_response opens streamGenerateContent for SSE
  passthrough, enforcing alt=sse via merge_alt_sse.

Unit tests cover URL building and alt=sse merging.
 2026-06-22 08:39:26 +08:00
boos 24a8dec151 fix: define DEFAULT_NEW_USER_MAX_COST_USD and repair test AppConfig initializers 
Pre-existing breakage on this branch (introduced by the billing commits),
unrelated to the Gemini work but blocking both `cargo build` and
`cargo test`:

- admin/users.rs imported routes::auth::DEFAULT_NEW_USER_MAX_COST_USD,
  which was never defined. Add it to auth.rs as $1.0 (the billing design's
  "new users default to $1" starter allowance).
- AppConfig gained `payment` and `pixelle_video` fields but several test
  helpers still used struct literals missing them. Initialize both with
  Default::default() at each affected test site.
 2026-06-22 08:39:17 +08:00
boos 9078b8d41a feat(gateway): client integration templates endpoint 
Add GET /api/cli-profiles/templates returning copy-ready config snippets
for pointing common AI clients at this gateway: Cursor, VS Code Continue,
Claude Code, and a generic OpenAI-compatible blob.

Ported from AQBot's list_gateway_templates (a desktop app that hardcodes
localhost:8080). Adapted for server-side use: the gateway origin is resolved
per request — ?base_url= override, then X-Forwarded-Proto + Host (correct
behind a TLS-terminating proxy), then config server.host:port fallback
(0.0.0.0/:: rewritten to 127.0.0.1, matching the comfyui-agent local-base
convention). OpenAI-compatible clients get the /v1 base; Claude Code gets
the bare origin since it appends /v1/messages itself.

Scope guard: this only returns config strings + copy hints. It deliberately
does not rewrite local CLI config files (AQBot's desktop cli_config behavior),
which has no meaning on a server.

New module proxy::cli_profiles::templates holds the snippet content; the admin
handler resolves the origin. Covered by 9 unit tests.
 2026-06-22 06:31:14 +08:00
boos d548525ef2 refactor(workflow_ui): 抽出 bootstrap 子模块 
Co-Authored-By: Claude <noreply@anthropic.com>
 2026-06-18 22:52:59 +08:00
boos 3aa1468fbb refactor(workflow_ui): 抽出 ws 子模块 
Co-Authored-By: Claude <noreply@anthropic.com>
 2026-06-18 22:44:53 +08:00
boos f7f9a9ca09 refactor(workflow_ui): 抽出 run_convert 子模块 
Co-Authored-By: Claude <noreply@anthropic.com>
 2026-06-18 22:32:51 +08:00
boos a37546cb2d refactor(workflow_ui): 抽出 native_proxy 子模块 
Co-Authored-By: Claude <noreply@anthropic.com>
 2026-06-18 22:22:19 +08:00
boos f43daed3ee refactor(workflow_ui): 抽出 repair 子模块 
Co-Authored-By: Claude <noreply@anthropic.com>
 2026-06-18 22:05:30 +08:00
boos 35f63c46f1 refactor(workflow_ui): 抽出 model_inject 子模块 
Co-Authored-By: Claude <noreply@anthropic.com>
 2026-06-18 21:55:27 +08:00
boos e296c01b4b docs: workflow_ui/mod.rs 续拆(6 子模块)设计 
把 mod.rs 残留 4095 行按职责再拆 6 组(model_inject/repair/native_proxy/
run_convert/ws/bootstrap),mod.rs 瘦到 ~1000-1200。纯机械移动,编译器+5测试验证。

Co-Authored-By: Claude <noreply@anthropic.com>
 2026-06-18 21:33:55 +08:00
boos a6c4db64c4 refactor(workflow_ui): 抽出 queue 子模块 
Co-Authored-By: Claude <noreply@anthropic.com>
 2026-06-18 15:15:17 +08:00
boos 7a02545fb8 refactor(workflow_ui): 抽出 validate 子模块 
Co-Authored-By: Claude <noreply@anthropic.com>
 2026-06-18 14:58:58 +08:00
boos 9cad69b88c refactor(workflow_ui): 抽出 comfy_proxy 子模块 
Co-Authored-By: Claude <noreply@anthropic.com>
 2026-06-18 14:47:24 +08:00
boos bbf0a3b81a refactor(workflow_ui): 抽出 assets 子模块 
Co-Authored-By: Claude <noreply@anthropic.com>
 2026-06-18 14:34:46 +08:00
boos 334ed04a6a refactor(workflow_ui): 抽出 models 子模块 
Co-Authored-By: Claude <noreply@anthropic.com>
 2026-06-18 14:23:17 +08:00
boos 7b1167bd75 refactor(workflow_ui): 抽出 node_defs 子模块 
Co-Authored-By: Claude <noreply@anthropic.com>
 2026-06-18 14:13:27 +08:00
boos 8a55efbfb6 refactor(workflow_ui): 抽出 auth 子模块 
Co-Authored-By: Claude <noreply@anthropic.com>
 2026-06-18 14:05:15 +08:00
boos fd4c1f0ac1 refactor(workflow_ui): 文件转目录模块(mod.rs,内容不变) 
Co-Authored-By: Claude <noreply@anthropic.com>
 2026-06-18 13:59:03 +08:00
boos 60ecd8a13c docs: workflow_ui.rs 拆分实现计划(Task0转目录 + 7子模块抽取) 
每任务抽1组函数(纯搬运)+cargo编译+测试验证+独立提交。通用6步流程统一。

Co-Authored-By: Claude <noreply@anthropic.com>
 2026-06-18 13:52:26 +08:00
boos 441adcf489 docs: workflow_ui.rs 拆分(8 子模块)设计 spec 
把 6181 行单文件按职责拆成 workflow_ui/ 目录 8 子模块(assets/auth/node_defs/
models/comfy_proxy/validate/queue/mod)。纯机械移动零逻辑改动,编译器+5测试验证。

Co-Authored-By: Claude <noreply@anthropic.com>
 2026-06-18 13:48:18 +08:00
boos 7e824a6d45 feat(digital-human): 副标题保留,仅去掉「基于 Pixelle-Video」前缀 
Co-Authored-By: Claude <noreply@anthropic.com>
 2026-06-18 13:35:08 +08:00
boos b2f6b875a0 feat(digital-human): 头部标题改为「短视频工厂/数字人」,去掉 Pixelle 副标题 
Co-Authored-By: Claude <noreply@anthropic.com>
 2026-06-18 13:34:14 +08:00
boos 86a2c51b31 feat(digital-human): 脚本模型选择器移到「文案与 BGM」区 
脚本生成属文案环节,把脚本模型(可选)下拉从「语音与画面」移到「文案与 BGM」区。

Co-Authored-By: Claude <noreply@anthropic.com>
 2026-06-18 13:27:08 +08:00
boos edc125f79c feat(nav): 移除短视频工厂菜单,数字人改名为「短视频工厂/数字人」 
admin/user 两区导航去掉 money-printer 入口,digital-human 菜单标签改为
「短视频工厂/数字人」。路由与页面保留(直链 /money-printer 仍可达,只是不在导航)。

Co-Authored-By: Claude <noreply@anthropic.com>
 2026-06-18 13:21:40 +08:00
boos 1d19401424 feat(pixelle): 连接管理页加 Pixelle 连接卡片 
Accounts 页加 Pixelle 连接卡片(URL+2key+保存),api.ts adminApi 加 get/savePixelleConnection。
api.ts 一并带入此前累积的 files URL 改写改动。

Co-Authored-By: Claude <noreply@anthropic.com>
 2026-06-18 13:13:57 +08:00
boos 92d38bb309 feat(pixelle): 连接凭证 admin 端点(GET/PUT 掩码 + 重启) 
Co-Authored-By: Claude <noreply@anthropic.com>
 2026-06-18 11:57:23 +08:00
boos 55188e51ff feat(pixelle): 连接凭证 service(settings 读写 + config.yaml 同步) 
Co-Authored-By: Claude <noreply@anthropic.com>
 2026-06-18 11:51:47 +08:00
boos 96b8d2c399 feat(pixelle): 加 serde_yaml + Pixelle config 路径配置项 
Co-Authored-By: Claude <noreply@anthropic.com>
 2026-06-18 11:43:55 +08:00
boos 284cf84a47 docs: Pixelle 连接凭证管理实现计划(5 任务) 
serde_yaml+config路径 → service(settings读写+yaml同步+restart) → admin端点(掩码)
→ 前端连接管理卡片 → 部署联调。写文件+重启容器同步机制。

Co-Authored-By: Claude <noreply@anthropic.com>
 2026-06-18 11:33:05 +08:00
boos 973396aac4 feat(digital-human): 后端转发 llm_model 给 Pixelle 
Co-Authored-By: Claude <noreply@anthropic.com>
 2026-06-18 11:23:23 +08:00
boos 1598e6c758 feat(digital-human): 前端加脚本模型选择器(llm_model) 
Co-Authored-By: Claude <noreply@anthropic.com>
 2026-06-18 11:23:19 +08:00
boos 07e31e0f7c docs: Pixelle 连接凭证纳入 BoosAPI 管理 设计 spec 
连接管理页加 Pixelle 连接卡片(runninghub key/comfy url/comfy key),
写 settings 表 + 同步 config.yaml + 重启容器生效。只管3凭证,写文件+重启机制。

Co-Authored-By: Claude <noreply@anthropic.com>
 2026-06-18 11:19:39 +08:00
boos bfafc8f226 docs: 数字人脚本默认模型改为 deepseek-v4-flash 
Co-Authored-By: Claude <noreply@anthropic.com>
 2026-06-18 11:05:26 +08:00
boos 230eef96ed docs: 数字人脚本 LLM 模型可选 设计 spec 
数字人页加脚本模型下拉(只列文本模型,默认 gpt-5.5),三层:
前端选择器(getModelsMarketplace过滤)+ 后端转发 llm_model + Pixelle 脚本步传 model。
生图模型已由图片工作流下拉覆盖,不在范围。

Co-Authored-By: Claude <noreply@anthropic.com>
 2026-06-18 04:50:05 +08:00
boos 054343f489 feat(digital-human): 后端转发 api_video_workflow 给 Pixelle 
Co-Authored-By: Claude <noreply@anthropic.com>
 2026-06-18 03:05:29 +08:00
boos 3524a165e3 feat(digital-human): 前端加视频工作流选择器(api_video_workflow) 
Co-Authored-By: Claude <noreply@anthropic.com>
 2026-06-18 02:57:44 +08:00
boos 53f99affec docs: 数字人 Comfy 视频入口实现计划(4 任务三层) 
前端视频工作流选择器 → 后端转发 api_video_workflow → Pixelle comfy 注入 audio_path
→ 部署联调。视频入口可选、默认不启用、向后兼容。

Co-Authored-By: Claude <noreply@anthropic.com>
 2026-06-18 02:54:26 +08:00
boos 30b7b12682 docs: 数字人接入 Comfy Cloud 视频工作流(完整视频入口)设计 
调查确认 BoosAPI 数字人 UI 无视频工作流入口、后端不转发 api_video_workflow、
Pixelle 仅给 api/ 通道注入 audio_path。设计贯穿三层补齐:
前端加视频工作流选择器 + 后端转发 api_video_workflow + Pixelle 给 comfy 工作流注入 audio_path。

Co-Authored-By: Claude <noreply@anthropic.com>
 2026-06-18 02:48:49 +08:00
boos 937442df04 docs: LTX2.3 数字人工作流实现计划(5 任务) 
获取API导出 → 改造工作流(标记+删RecordAudio) → 补 media.py image_path 转发
→ 校验探测 → 真实联调。硬依赖用户导出 API 格式 JSON。

Co-Authored-By: Claude <noreply@anthropic.com>
 2026-06-18 02:20:36 +08:00
boos 79ade45c25 docs: LTX2.3 数字人 spec 补充 media.py image_path 转发缺口 
writing-plans 阶段发现:media.py 只给 api/ 通道转发 image_path,comfy/ 通道收不到肖像图。
增加 media.py 一行级改动(非 api 分支把 image_path 加入 workflow_params),
标记名对齐为 $~image_path! / $~audio_path! / $prompt!。

Co-Authored-By: Claude <noreply@anthropic.com>
 2026-06-18 02:17:12 +08:00
boos ff514061d7 docs: LTX2.3 数字人工作流(Comfy Cloud)设计 spec 
用官方模板 video_ltx2_3_id_lora(LTX2.3 身份保持+音频驱动)做 Pixelle comfy/ 数字人工作流,
经 comfy-cloud 适配器执行。模型/节点已验证在 Comfy Cloud 托管齐全。
comfykit _meta.title 标记注入(image/audio/prompt)。硬依赖:用户导出 API 格式 JSON。

Co-Authored-By: Claude <noreply@anthropic.com>
 2026-06-18 02:12:03 +08:00
boos 8ca6c2ad4f feat(comfy-cloud): Comfy Cloud 预设移到首位 + 新增站点默认选中 
预设数组把 comfy-cloud 排第一;站点管理 openAdd 默认选 Comfy Cloud 预设
(预填 url+platform,只需贴 X-API-Key)。detect-race 测试补平台重置以保留竞态覆盖。

Co-Authored-By: Claude <noreply@anthropic.com>
 2026-06-18 00:38:32 +08:00
boos d850da64c3 feat(comfy-cloud): 站点预设模板新增 Comfy Cloud 
siteInitializationPresets 共享契约(ts/js/d.ts)加 comfy-cloud 预设:
platform=comfy_cloud, defaultUrl=https://cloud.comfy.org, 自动填充官方地址。
platform 联合类型扩 'comfy_cloud';urlMatcher + Rust detect_site_platform 同步识别。

Co-Authored-By: Claude <noreply@anthropic.com>
 2026-06-18 00:21:44 +08:00
boos 08a2980f5f fix(comfy-cloud): /history 完成分支校验 jobs 详情状态码 
Co-Authored-By: Claude <noreply@anthropic.com>
 2026-06-17 23:39:18 +08:00
boos 7758858141 feat(comfy-cloud): 挂载适配路由 + 站点管理 comfy_cloud 平台选项 
Co-Authored-By: Claude <noreply@anthropic.com>
 2026-06-17 23:30:46 +08:00
boos 8676b5486b feat(comfy-cloud): /view 产出文件透传 
Co-Authored-By: Claude <noreply@anthropic.com>
 2026-06-17 23:26:07 +08:00
boos e90beda1a5 feat(comfy-cloud): /history 轮询翻译(status+jobs→history) 
Co-Authored-By: Claude <noreply@anthropic.com>
 2026-06-17 23:21:44 +08:00
boos 03eea2e267 feat(comfy-cloud): 适配端点骨架 + POST /prompt 转发 
Co-Authored-By: Claude <noreply@anthropic.com>
 2026-06-17 23:18:34 +08:00
boos 70c11a15cd feat(comfy-cloud): job→ComfyUI history 翻译函数 
Co-Authored-By: Claude <noreply@anthropic.com>
 2026-06-17 23:10:42 +08:00
boos 17cd0691ca feat(comfy-cloud): 站点配置读取 resolve_comfy_cloud_site 
Co-Authored-By: Claude <noreply@anthropic.com>
 2026-06-17 23:08:16 +08:00
boos 2d273a03ad docs: Comfy Cloud 适配器实现计划(7 任务 TDD) 
站点配置读取 → job→history 翻译 → 三个适配端点(prompt/history/view)
→ 挂载+前端平台选项 → 真实联调。全程 TDD,wiremock 集成测,逐任务提交。

Co-Authored-By: Claude <noreply@anthropic.com>
 2026-06-17 23:02:16 +08:00
boos e1d0ade434 docs: Comfy Cloud 工作流执行适配器设计 spec 
在 BoosAPI 内做 ComfyUI 原生协议↔Comfy Cloud API 翻译适配器:对外暴露
/comfy-cloud/{prompt,history,view},内部翻译成 cloud.comfy.org/api/* + X-API-Key。
Comfy Cloud base_url+key 经站点管理(新增 comfy_cloud 平台类型)录入。
Pixelle/comfykit 零改动,只改 comfyui_url 指向适配端点。

Co-Authored-By: Claude <noreply@anthropic.com>
 2026-06-17 22:56:55 +08:00
boos e8508cb056 feat: Codex 工作区改动迁移(支付管理/用户余额/创作页等) 
将 Codex 在工作区累积的改动整体落到 refactor/rust-backend:
支付管理与用户余额页、各创作 surface、website 等。排除 boosapi.db/config.toml 等敏感文件。

Co-Authored-By: Claude <noreply@anthropic.com>
 2026-06-17 22:28:14 +08:00
boos bfd804f719 feat(billing): UsageRecords dual-track ledger view 
api.ts 新增 userApi.getBillingLedger / getBillingSummary 及 Billing* 类型;
UsageRecords.tsx 增加 USD/积分 双轨切换 tab、积分汇总卡与明细表(切到积分轨时懒加载)。
随文件一并提交此前累积的支付/Comfy Cloud/工作流前端 API 改动。

Co-Authored-By: Claude <noreply@anthropic.com>
 2026-06-17 03:04:11 +08:00
boos e7f3da5961 feat(billing): user billing ledger + summary endpoints 
新增 GET /api/user/billing/ledger 与 /api/user/billing/summary 两个用户侧接口,
基于 Task11 的 list_user_ledger / summarize_user_ledger 返回当前用户的明细与聚合。
随文件一并提交此前累积的充值/支付/市场相关改动及测试辅助。

Co-Authored-By: Claude <noreply@anthropic.com>
 2026-06-17 02:56:12 +08:00
boos 5cfd533d89 feat(billing): user ledger list + summary queries 2026-06-17 01:49:46 +08:00
boos 0b7abed79a docs: 细化计费第3期(消费明细)TDD Task11-14 2026-06-17 01:44:28 +08:00
boos a89edf6f75 feat(payment): comfy 登录态/充值确认/记录管理 + Task9 积分到账调用适配 
含本会话累积的支付路由功能(firebase-login 回执登录、recharge-records
列表/确认/清空、诊断卡)及 admin_confirm_user_recharge 传 config 的调用适配,
使计费 Task9(comfy 充值改积分)调用方编译完整。

Co-Authored-By: Claude <noreply@anthropic.com>
 2026-06-16 21:13:16 +08:00
boos 5d42671172 feat(billing): comfy recharge to points + admin credit adjust 
Co-Authored-By: Claude <noreply@anthropic.com>
 2026-06-16 21:11:44 +08:00
boos ca9e45c59c feat(billing): workflow points gating + charge 
Co-Authored-By: Claude <noreply@anthropic.com>
 2026-06-16 20:58:02 +08:00
boos be7538a1da feat(billing): workflow_points_cost config 2026-06-16 20:32:10 +08:00
boos cfe2098b73 feat(billing): points track apply_points_delta + balance 2026-06-16 20:24:50 +08:00
boos bd464016a8 docs: 细化计费第2期(积分轨)TDD 任务 Task6-10 2026-06-16 20:20:22 +08:00
boos 7e8430934e feat(billing): USD admin adjust writes credit_ledger 
Co-Authored-By: Claude <noreply@anthropic.com>
 2026-06-16 17:46:56 +08:00
boos ab2fd271e8 feat(billing): USD recharge writes credit_ledger 2026-06-16 17:40:43 +08:00
boos 4dd2be4cc3 feat(billing): USD consume writes credit_ledger in one tx 
Co-Authored-By: Claude <noreply@anthropic.com>
 2026-06-16 17:34:21 +08:00
boos fd94303433 feat(billing): credit_ledger schema + record_ledger_entry 2026-06-16 17:25:59 +08:00
boos 91dcbc5c53 docs: 计费闭环实现计划(第1期详细TDD + 后5期概要) 
第1期地基: credit_ledger + user_credits 表, USD 轨三处记账
(消费/充值/管理员调整)同事务接入 ledger。每步含完整测试与代码。

Co-Authored-By: Claude <noreply@anthropic.com>
 2026-06-16 17:17:54 +08:00
boos 278b0c66b8 docs: 计费闭环系统设计 spec 
双轨额度(USD 池 + 工作流积分池)、ledger-first 统一流水账、
消费明细/充值档位/超额预警/全量审计四块功能、A+C 混合积分计费、
Comfy 余额对账校准。分 6 期实现。

Co-Authored-By: Claude <noreply@anthropic.com>
 2026-06-16 17:12:02 +08:00
boos d697146941 feat(audit): login audit log with account info and IPv4 
- 审计日志记录具体账号（用户名<邮箱>）
- 优先显示 IPv4，保留 IPv6
- Program Logs 页面新增 account/IPv4 列
 2026-06-10 19:54:32 +08:00
boos d1f3f4e93d feat(payment): Stripe Checkout payment module 
- payment_orders 建表迁移，支持多 provider（stripe）
- Stripe Checkout Session 创建、Webhook 验签、到账
- 支付成功自动为 API Key 增加额度
- payment.enabled 开关，关闭时不影响旧 Comfy Checkout
 2026-06-10 19:54:27 +08:00
boos df97633300 fix(recharge): per-amount distinct checkout URLs 
- 前端 /0/0/0 各自携带独立 checkoutUrl
- 后端按金额解析独立 Checkout URL 配置
- 同时校验 optionId 和 amountUsd 防止金额错配
- 移除旧单一固定 checkout URL 兜底
 2026-06-10 19:54:20 +08:00
boos 3d54c7d529 fix: support user recharge record cancellation 2026-06-09 17:22:23 +08:00
boos 55b3d4d99a feat: enhance new website experiment motion 2026-06-09 16:59:04 +08:00
boos 59106e6a96 feat: refine BoosAPI console and user workspace 2026-06-09 16:48:18 +08:00
boos aaba6f152e perf: optimize proxy streaming and database access 2026-06-07 00:00:24 +08:00
boos f3d2d50f9a fix: make website boot animation resilient 2026-06-06 22:38:31 +08:00
boos 16162095f7 style: polish admin operations pages 2026-06-06 22:19:42 +08:00
boos 6629d9d0a3 fix: stabilize console topbar layout 2026-06-06 22:09:44 +08:00
boos 3c6f061709 fix: improve assistant thinking and image progress 2026-06-06 22:02:45 +08:00
boos d7d14e077e fix: stabilize website boot loader 2026-06-06 21:54:25 +08:00
boos 3b3292b934 feat: add admin operations war room 2026-06-06 21:50:23 +08:00
boos f7916a42e5 feat: enhance website flow and user workbench 2026-06-06 21:44:58 +08:00
boos f725de28bd feat: polish website and console dashboards 2026-06-06 21:15:33 +08:00
boos 97113964c8 fix: remove sidebar identity card 2026-06-06 21:01:20 +08:00
boos b429695cba fix: stabilize topbar layout 2026-06-06 20:57:33 +08:00
boos d6bf7352a0 feat: support local avatar uploads 2026-06-06 20:52:34 +08:00
boos d800ed1f9f fix: keep admin sidebar actions visible 2026-06-06 20:44:34 +08:00
boos 4855db3fc8 feat: polish user auth entrance 2026-06-06 20:38:18 +08:00
boos 6cd0a8caca fix: stream real agent reasoning 2026-06-06 20:26:31 +08:00
boos 44dc89a0dd refactor: share console page header 2026-06-06 20:18:28 +08:00
boos 823ac3c25d fix: show only generated outputs in workspace 2026-06-06 20:03:02 +08:00
boos 5ecea182bc feat: polish console shell and notification settings 2026-06-06 19:56:56 +08:00
boos cd843465b2 feat: show conversation content in usage logs 2026-06-06 19:36:42 +08:00
boos ef0f91e683 perf: speed up app loading 2026-06-06 19:21:59 +08:00
boos 9c1e5ae293 fix: keep video assistant reasoning label stable 2026-06-06 19:02:41 +08:00
boos 00b3365f5a feat: refine website gateway os hero 2026-06-06 18:59:10 +08:00
boos d5babf5f3f fix: support website color schemes 2026-06-06 18:45:12 +08:00
boos 4b757b8250 feat: add light website intro motion 2026-06-06 18:29:10 +08:00
boos def8d7a204 chore: speed up local build workflow 2026-06-06 18:10:16 +08:00
boos 25c6fdbd6c revert website high contrast redesign 2026-06-06 17:58:10 +08:00
boos 47202e6848 redesign website with high contrast motion 2026-06-06 17:54:38 +08:00
boos 1b2880739a polish auth entry surfaces 2026-06-06 17:42:14 +08:00
boos 188e457e7f polish topbar user experience 2026-06-06 17:31:41 +08:00
boos 13756adc9d polish about page experience 2026-06-06 17:25:31 +08:00
boos f026582008 fix: persist runtime proxy token 2026-06-06 17:11:51 +08:00
boos b3eb86d5ea chore: remove update center 2026-06-06 16:55:15 +08:00
boos 301d086cb6 fix: show runtime logs in program logs 2026-06-06 16:40:55 +08:00
boos 023384b14b style: refine website section spacing 2026-06-06 16:18:11 +08:00
boos d315f0ffe2 feat: polish website model radar 2026-06-06 16:14:05 +08:00
boos f0385c9c8c chore: install vercel agent skills 2026-06-06 16:07:34 +08:00
boos 339f91d014 feat: sync upstream analytics schema support 2026-06-06 16:07:13 +08:00
boos 0d231ec467 feat: enhance website model radar motion 2026-06-06 15:46:51 +08:00
boos be1fc1df48 feat: optimize routes and registration UX 2026-06-06 15:37:37 +08:00
boos dd874bae30 feat: refresh BossAI console frontend 2026-06-06 15:25:04 +08:00
boos 45aa741d9c feat: refine BossAI console and website design 2026-06-06 15:09:53 +08:00
boos 49c398db5e feat: polish BossAI website motion 2026-06-06 14:56:33 +08:00
boos 4d748dd938 feat: refine BossAI website product story 2026-06-06 06:27:28 +08:00
boos b40c522749 feat: add gsap motion to BossAI website 2026-06-06 06:18:40 +08:00
boos d467e27fd8 fix: guard embedded frontend assets 2026-06-06 06:11:15 +08:00
boos 5ef017c54e feat: serve website at root path 2026-06-06 05:59:48 +08:00
boos 03046152fd feat: isolate BossAI website with Next.js 2026-06-06 05:30:10 +08:00
boos d75daf72d6 feat: add premium public landing page 2026-06-06 05:06:37 +08:00
boos d39100b56d feat: optimize money printer factory 2026-06-06 04:56:02 +08:00
boos 2e4c5801b6 chore: tighten repository hygiene 2026-06-06 04:40:25 +08:00
boos 870b2a2da3 feat: surface admin settings attention states 2026-06-06 03:57:15 +08:00
boos 4448567368 feat: optimize admin settings page 2026-06-06 03:49:30 +08:00
boos fae0f607aa test: restore project verification suite 2026-06-06 03:35:29 +08:00
boos e4630c4cb6 fix: harden workflow smoke issues 2026-06-06 03:23:39 +08:00
boos e72e323313 feat: refine money printer comfy template mode 2026-06-06 03:09:08 +08:00
boos 2b836b3e1e Add built-in Cloud video template fallback 2026-06-06 02:58:16 +08:00
boos 598b2f48d6 Handle Comfy Cloud video job status 2026-06-05 22:01:03 +08:00
boos 3f22d7b1ab Make short video factory use Comfy templates 2026-06-05 21:35:12 +08:00
boos 5ce5ea1687 Route Comfy workflows through video API 2026-06-03 11:39:14 +08:00
boos f8741b544e Filter MoneyPrinter Comfy video templates 2026-06-03 11:29:55 +08:00
boos c316a78511 Default MoneyPrinter videos to BoosAPI route 2026-06-03 11:03:04 +08:00
boos 68ae9acb27 Clarify bundled Picture Agent template errors 2026-06-03 11:01:47 +08:00
boos 13c7d8aa4e Remove stale Picture Agent remote template state 2026-06-03 10:59:11 +08:00
boos fb5fc9f1ae Use bundled Linux Do picture templates 2026-06-03 10:55:43 +08:00
boos 5765ea48b0 Clarify Picture Agent template refresh state 2026-06-02 17:38:54 +08:00
boos 55bd3f41f8 Follow Picture Agent gallery data URL 2026-06-02 17:30:15 +08:00
boos 938597b766 Fix Picture Agent loading fallback 2026-06-02 17:23:36 +08:00
boos fe0e3faa22 Generate MoneyPrinter Comfy prompts from form 2026-06-02 17:18:23 +08:00
boos d0f26118ff Normalize MoneyPrinter Comfy workflow templates 2026-06-02 17:11:15 +08:00
boos c98d9a2c6d Load Comfy templates for MoneyPrinter 2026-06-02 17:00:46 +08:00
boos 1293ebae68 Use Comfy API for MoneyPrinter video generation 2026-06-02 16:47:48 +08:00
boos b29c7ffa7a Add native MoneyPrinter short video factory 2026-06-02 15:26:42 +08:00
boos 056e9fb651 Improve digital human template UI 2026-06-02 12:17:05 +08:00
boos fa5a2419d8 Add Comfy digital human jobs 2026-06-02 11:07:31 +08:00
boos 7b34153235 Proxy external template requests 2026-06-01 11:21:56 +08:00
boos 04792bd3f7 Improve offline template loading 2026-06-01 11:02:36 +08:00
boos bb31118792 Reference local Workflow UI repo directly 2026-05-28 17:19:32 +08:00
boos 5027767ca2 Use local Workflow UI source for BossAI deploy 2026-05-28 17:16:12 +08:00
boos fd930757f9 Move BossAI deploy worktree out of tmp 2026-05-28 17:03:08 +08:00
boos eb6ed11cff Add BossAI Debian deploy script 2026-05-28 16:59:51 +08:00
boos 931bcf3fb9 Update BossAI workflow and workspace experience 2026-05-28 10:32:20 +08:00
boos e0bd9b4194 Embed workflow UI and isolate workspace assets 2026-05-26 17:00:10 +08:00
boos 0f9fe4a81d chore: prune legacy node backend and mix workflow models 2026-05-26 15:18:33 +08:00
boos 6869504119 chore: add optional bun frontend build 2026-05-25 22:05:03 +08:00
boos 3f9f9f7665 docs: remove readme screenshots 2026-05-25 21:43:46 +08:00
boos a1f3400af3 docs: add hardware requirements 2026-05-25 21:41:47 +08:00
boos da686ecda4 chore: vendor workflow ui as submodule 2026-05-25 21:19:49 +08:00
boos 1ba293c262 feat: polish workflow studio and workspace assets 2026-05-25 20:42:38 +08:00
boos cb35d5fc6e feat: add workflow studio and postgres support 2026-05-25 16:03:07 +08:00
boos 7cdb02ef1d feat: add workspace and claude messages support 2026-05-22 05:57:37 +08:00
boos c1074ddf71 Integrate ComfyUI agents and video workflows 2026-05-22 04:46:15 +08:00
boos 3c12738138 fix: allow comfyui assets through proxy 2026-05-22 01:27:57 +08:00
boos 8de175a8c5 feat: add comfyui agent attachments 2026-05-22 01:16:37 +08:00
boos 7c6364a160 fix: enable multi tenant comfy workspace 2026-05-22 00:44:57 +08:00
boos 5ef3f8aea8 fix: route video workspace to comfyui proxy 2026-05-21 17:27:41 +02:00
boos 9e7ce80574 fix: complete account token admin routes 2026-05-21 17:16:24 +02:00
boos 65d2f1bbe5 fix: restore account health tokens and dashboard data 2026-05-21 17:07:18 +02:00
boos 0207ba748f fix: use user api key for comfyui agent 2026-05-21 16:55:32 +02:00
boos d0912e44b4 fix: route video agent to comfyui and ignore openspec 2026-05-21 16:44:30 +02:00
boos 9c84759498 feat: merge opus comfyui and login updates 2026-05-21 16:32:04 +02:00
boos c16479da7c fix(rust): sweep orphan route_channels when their model has no active account 
The per-route loop in `rebuild_routes` only visits routes whose model_pattern
appears in the current `by_model` set. When the last active account for a
model goes away (account deleted, status flipped, model dropped from
model_availability), the model falls out of `by_model` entirely and its
existing auto-managed channels are never reconciled — they stay behind
pointing at a route nothing can serve.

Add a final orphan sweep over all auto-managed route_channels. Anything whose
route wasn't processed in the per-route loop gets hard-deleted. Manual-override
channels still get the same exemption as before.

Covered by two new in-memory sqlite tests:
- orphan_channel_is_cleaned_when_last_account_goes_inactive
- orphan_sweep_preserves_manual_channels
 2026-05-20 19:58:45 +08:00
boos 423912277b fix(build): reuse multi-tenant ComfyUI image instead of rebuilding every run 
- skip docker build when boosapi-comfyui:multi-tenant already exists;
  --rebuild-image opts back into a fresh build
- fall back to `docker load` from docker/boosapi-comfyui-multi-tenant-*.tar
  when the image is absent but the saved tar is present
- gate the whole block on `docker info` so a client-only host doesn't hang
  on build when the daemon is unreachable
 2026-05-20 19:40:39 +08:00
boos cf696c01a5 fix(rust): trigger route rebuild on account writes; add segment filter 
- spawn_route_rebuild after create / delete / model refresh / manual model
  upsert; gate update_account on status change so cosmetic edits don't
  burn a transaction
- list_accounts now accepts ?segment=apikey|session|oauth, filtered against
  extra_config.$.credentialMode (legacy null rows treated as apikey)
 2026-05-20 19:35:53 +08:00
boos 7c9a1e2cc4 fix(rust): match main's drizzle-style camelCase response shape 
Frontend reads main's drizzle-generated camelCase fields (siteId,
accessToken, oauthProvider, etc.) and a nested `site: {...}` on each
account row. Rust models were serializing snake_case with no nested
site, so PUT /api/sites/undefined/disabled-models 404s, account.site?.id
is undefined everywhere, and similar shape mismatches break Accounts,
Sites, Tokens, and Dashboard pages.

- Add #[serde(rename_all = "camelCase")] to every model struct in
  src/db/models/* (Account, AccountToken, Site, User, Event,
  TokenRoute, RouteChannel, BackgroundTask, DownstreamApiKey,
  Organization/Member/Invitation, SiteAnnouncement)
- list_accounts now nests `site: {...}` per row, matching main's
  `{...account, site: {...}}` shape from accountsOverviewService
- admin user-detail endpoint emits camelCase keys (totalRequests,
  totalCost, last7DaysCost, recentLogs, promptTokens, completionTokens,
  totalTokens, createdAt) to match the frontend
- routes refresh endpoint now emits both affected_routes and
  affectedRoutes for forward compat

Co-Authored-By: Kiro <noreply@kiro.dev>
 2026-05-20 07:21:40 +08:00
boos 9c0d4ec69f feat(rust): wire downstream-key billing, add /v1/responses, ComfyUI shim 
Previously every executor took `_state: AppState` (unused) and `check_auth`
discarded the matched downstream key id, so `usage_logs` was orphan code.
This change plumbs the key id from auth → handlers → executors → billing,
adds the OpenAI Responses API endpoint, and exposes shim aliases under
`/api/comfyui-agent/proxy/openai/*` so embedded ComfyUI's OpenAI nodes
flow through the same auth/conductor/billing pipeline.

- check_auth now returns Option<i64> (managed key id) instead of unit
- record_billing helper writes usage_logs after each successful upstream call
- extract_usage handles both chat-completions and responses usage shapes
- conductor wrappers record billing post-Success; stream variant scans
  chunks in reverse for the final usage event
- POST /v1/responses (stream + non-stream) via ProxyConductor
- shim aliases mounted on the same Router so auth/failover/billing work for free
- ComfyUIProcess injects BOOSAPI_BUILTIN_KEY env + --comfy-api-base on spawn
- bootstrap built-in `comfyui-agent` downstream key at startup (idempotent)
- get_auth_header in vendored ComfyUI falls back to BOOSAPI_BUILTIN_KEY env

Co-Authored-By: Kiro <noreply@kiro.dev>
 2026-05-20 06:20:39 +08:00
boos 22751effd5 fix: refresh user logout state 2026-05-19 10:41:40 +02:00
boos 4fe84707e5 feat: complete user login admin keys and deployment docs 2026-05-19 10:06:52 +02:00
boos 812a7c6c07 fix: persist site api endpoints and account verification 2026-05-19 11:22:09 +08:00
boos b6aae5f301 feat: unify user and admin login entry 2026-05-19 10:53:38 +08:00
boos 27c2aca312 fix: show site presets and api key site options 2026-05-19 10:49:41 +08:00
boos 11144d0697 fix: complete gemini frontend and usage follow-up 2026-05-19 10:37:29 +08:00
boos 31e95c2634 fix: usage SQL 查询 ambiguous column 
l.created_at 缺少表别名前缀导致歧义错误
 2026-05-19 03:06:11 +08:00
boos 499dba6104 fix: 完善用户路由和注册回调 
- App.tsx 导入 hasValidUserSession 修复 TS 编译错误
- UserRegister 增加 onLogin 回调，注册成功自动跳转
 2026-05-19 02:47:23 +08:00
boos d432ded68f feat: 用户管理页面增加用量统计标签 
- 用户列表新增总请求、总消耗($)、7天消耗列
- 点击用户行展开用量详情（趋势+最近日志）
- 添加"用量统计"标签页切换
 2026-05-19 02:47:19 +08:00
boos 1cef28169c feat: 管理员创建用户自动生成密钥 & 用量统计 API 
- create_user() 自动生成 sk-user-* 密钥并关联用户
  (使用事务确保用户+密钥原子创建)
- 新增 GET /api/admin/users/{id}/usage 返回用量统计
  (总请求/成本、7天成本、30天趋势、最近50条日志)
- api.ts 新增 getUserUsage(id) 方法
- mod.rs 导出 stats 模块供 user 路由复用
 2026-05-19 02:47:15 +08:00
boos a0d3743564 fix: 修复后端 API 路径不匹配 
Gemini 创建的路由为 /v1/user/logs 和 /v1/user/summary，
但前端 api.ts 调用的是 /api/user/logs 和 /api/user/summary，
改为 /api/ 前缀修复 404。
 2026-05-19 02:36:57 +08:00
boos c9e98df3f1 chore: 优化 ComfyUI Docker 配置 
- .dockerignore: 精简忽略规则
- config.toml: 添加 [comfyui] 配置段
- Dockerfile: 本地源码构建、清华镜像加速
 2026-05-19 02:33:23 +08:00
boos ba07517974 fix: 密钥管理排除站点列表缺少无账号站点 
loadExclusionSources() 原只从 accounts 提取站点，
新增的/无关联账号的站点不显示。
增加 api.getSites() 调用，合并所有站点到排除选项。
 2026-05-19 02:33:18 +08:00
boos c8a523d973 fix: 站点管理预设选项添加 label 标签 
SiteInitializationPreset 类型缺少 label 字段，
导致 coding plan、deepseek 等预设在下拉菜单显示空白。
给接口添加 label: string，全部 13 个预设补上中文标签。
 2026-05-19 02:33:13 +08:00
boos 5890a9b4ac feat: 添加用户端后端 API 路由 
- 新增 GET /api/user/logs（用户 API 调用历史）
- 新增 GET /api/user/summary（用户使用统计摘要）
- stats.rs: ProxyLogRow 改为 pub 供 user 模块复用
 2026-05-19 02:33:08 +08:00
boos bf00296a90 feat: 新增普通用户界面 
- 重构 App.tsx 路由，分离普通用户/管理员导航
  (userSidebarGroups / userAuthed 状态)
- UserDashboard 重写为概览页：用量统计、最近记录、快速入口
- 新增 UsageRecords 使用记录页（分页）
- 新增 UserKeys 密钥管理页（创建/删除 sk-user- 密钥）
- 新增 UserProfile 个人资料页（修改用户名/密码）
- UserLogin 增加 onLogin 回调
- api.ts 增加 userApi 工具方法
 2026-05-19 02:32:58 +08:00
boos 4f0c4959bf Merge pull request 'feat: update logo image' (#5) from feature/update-logo into refactor/rust-backend 
Reviewed-on: #5
 2026-05-18 09:24:44 +00:00
Aibo117 dbfe07c736 feat: update all logo and favicon files 
Replace logo.png, favicon.png, favicon-64.png, and desktop-icon.png
with the new brand logo.
 2026-05-18 17:23:54 +08:00
Aibo117 bde045d0cf feat: update logo image 
Replace the default logo with the new brand logo.
 2026-05-18 17:19:15 +08:00
boos e9595017e9 feat: support admin account login 2026-05-18 17:01:39 +08:00
boos f986fe0377 feat: complete Rust backend UI compatibility 2026-05-18 16:55:09 +08:00
boos f2434e725d feat: ComfyUI video assistant SaaS plan + shared types cleanup 
- Add plan/2026-05-18-comfyui-video-assistant-saas.md (gpt-5.5 generated)
- Add src/server/ and src/shared/ type definitions
- Update comfyui routes and api_key auth
- Remove old metapi docs, deploy/k3s, and deprecated configs
 2026-05-18 11:28:20 +08:00
boos bfdb01e542 feat: add 视频助手 nav item pointing to /comfyui-agent 2026-05-18 10:16:55 +08:00
boos 3779826a15 fix: add /api/users/login route alias for frontend compat; return JSON error for unmatched API routes instead of SPA index.html 2026-05-18 10:14:07 +08:00
boos b89b71a95f docs: update README tech stack and dev guide for Rust backend 
- Rewrote 技术栈 section (Axum/Tokio/SQLx/TokenRouter)
- Rewrote 本地开发 section (cargo run + npm build)
- Added 项目结构 section describing Rust backend layout
- Added 环境变量 reference (BOOSAPI_*__* naming)
- Updated Docker Compose examples for Rust config vars
- Removed all Node.js runtime/TypeScript refs from backend docs
 2026-05-18 09:37:04 +08:00
boos 0eb7c32585 fix: restore frontend source code (src/web/) that was accidentally deleted 
Frontend source is needed for development/building the SPA.
Only Node.js runtime server code should be removed.
 2026-05-18 09:33:56 +08:00
boos 5d29f03d50 refactor: purge Node.js, Rust is the one true backend 
- Moved boosapi-rs/* to repo root
- Deleted all Node.js source (src/server/, src/web/, scripts/)
- Deleted node_modules, package.json, tsconfig, vite.config
- Updated .gitignore and AGENTS.md for Rust-only stack
- Fixed static file path for frontend dist/web/
- Dockerfile stays the same (already Rust-only)
- Kept dist/web/ for Rust static serving
 2026-05-18 09:11:29 +08:00
boos 725f44699a refactor: ComfyUI Agent with structured parsing + image gen + TTS 
- New system prompt with 【CHARACTER】【SCENE】【TTS】【WORKFLOW】 markers
- Backend parses structured sections, auto-calls gpt-image-2 for character/scene images
- Auto-calls TTS API for dialogue lines
- Case-insensitive field parsing, robust whitespace handling
- Static file serving with SPA fallback for frontend
- No Node.js runtime dependency for serving
 2026-05-18 04:02:02 +08:00
boos 56391f2193 feat: Phase 5-6 - Proxy Conductor, Token Router, Services, Dockerfile 
- Proxy Conductor: retry/fallback/auth-refresh orchestration loop
- Token Router: exact/wildcard/regex model routing with channel selection
- Services: Cron scheduler, OAuth token refresh, Update center, Announcements
- User routes: profile + API key management
- DB queries module
- Dockerfile: multi-stage build
- Proxy routes integrated with Conductor + TokenRouter
 2026-05-18 03:00:09 +08:00
boos 78d46eeddb feat: Search routes migrated to Rust 
- POST /api/search — cross-entity search across 6 categories
- Searches: sites, accounts, account_tokens, checkin_logs,
  proxy_logs, and model_availability
- All via SQL LIKE, no external search engine dependency
- Model aggregation with deduplication
- 18/18 tests pass
 2026-05-17 17:15:03 +08:00
boos 7a3a88f738 feat: Monitor (LDOH proxy) routes migrated to Rust 
- GET/PUT /api/monitor/config — LDOH cookie management via settings table
- POST /api/monitor/session — cookie auth token
- GET /monitor-proxy/ldoh/{*path} — reverse proxy with content rewriting
- Cookie-based auth, HTML/JS/CSS path rewriting
- 18/18 tests pass
 2026-05-17 17:13:28 +08:00
boos adb349eecc feat: Stats routes — model-by-site + site-distribution 
- GET /api/stats/model-by-site — model usage aggregated by model name
- GET /api/stats/site-distribution — per-site usage summary
- Both query existing model_day_usage table with day-range filter
- 18/18 tests pass
 2026-05-17 17:10:35 +08:00
boos 15f73a2793 fix: ComfyUI wildcard route syntax for axum 0.8+ 
- Changed  to  in comfyui proxy route
- Added config.toml for local dev
- Verified: Rust backend starts and serves /healthz, /api/sites,
  /api/events, /api/tasks, /api/settings, /api/organizations/plans
- 18/18 tests pass
 2026-05-17 17:08:36 +08:00
boos fe1a7c2115 feat: User profile routes migrated to Rust 
- PATCH /api/users/me — update own username
- POST /api/users/me/password — change password (verify old first)
- GET /api/users/{id} — get user profile (self or admin)
- JWT auth for all endpoints
- 18/18 tests pass
 2026-05-17 17:04:54 +08:00
boos 07f427877b feat: Background task SSE streaming endpoint 
- Added /api/update-center/tasks/{id}/stream SSE endpoint
- Polls DB for task status updates every 1s (up to 2 min)
- Streams status + log events, ends on completion/timeout
- Added async-stream dependency
- 18/18 tests pass
 2026-05-17 17:03:12 +08:00
boos e94c6cf853 feat: Proxy extensions — audio, video, completions, embeddings 
- Generic execute_proxy_request executor for arbitrary paths
- POST /v1/completions, /v1/embeddings
- POST /v1/audio/speech, /v1/audio/transcriptions, /v1/audio/translations
- POST /v1/videos
- All reuse existing auth + route resolution infra
- 18/18 tests pass
 2026-05-17 17:01:15 +08:00
boos 84b4b16ebd feat: Proxy extensions — /v1/completions + /v1/embeddings 
- Added generic execute_proxy_request executor for any path suffix
- POST /v1/completions — forwards to upstream /completions
- POST /v1/embeddings — forwards to upstream /embeddings
- Both use existing auth + route resolution infra
- 18/18 tests pass
 2026-05-17 16:59:43 +08:00
boos 4ac9c2385f feat: Organizations + Invitations routes migrated to Rust 
- New migration: organizations, organization_members, invitations tables
- New model: Organization, OrganizationMember, Invitation
- Full CRUD: list/create/get/update orgs, members, invitations
- Public invitation lookup + accept flow
- JWT auth for all protected endpoints
- Admin role verification for org management
- 18/18 tests pass
 2026-05-17 16:58:27 +08:00
boos fac1aa4a88 feat: Background tasks table + tasks route migrated to Rust 
- New migration: background_tasks table
- New model: BackgroundTask (background_task.rs)
- GET /api/tasks with limit param
- GET /api/tasks/{id} with 404 handling
- 18/18 tests pass
 2026-05-17 16:56:15 +08:00
boos d7d3670f02 feat: User API Keys routes migrated to Rust 
- New user_api_keys.rs route module
- JWT-authenticated CRUD on downstream_api_keys scoped to user_id
- GET/POST/PATCH/DELETE /api/user-api-keys with ownership verification
- Uses existing downstream_api_keys table with user_id FK
- Supports all fields: name, tags, enabled, expires_at, max_cost, etc.
- 18/18 tests pass
 2026-05-17 13:37:17 +08:00
boos 9329248e59 feat: Site Announcements routes migrated to Rust 
- New SiteAnnouncement model (site_announcement.rs)
- Route handlers: list (with siteId/platform/read/status filters),
  mark read, mark all read, delete all
- In-memory status filtering for active/expired/dismissed (same as Node.js)
- Uses existing site_announcements table from migration
- 18/18 tests pass
 2026-05-17 13:34:53 +08:00
boos 2793a7990d feat: Checkin + Events routes migrated to Rust 
- /api/checkin — list logs, stats, accounts, toggle, run
- /api/events — list, count, mark read, clear
- CheckinLog + Event models
- cargo check ✅ | cargo test 18/18 ✅
 2026-05-17 13:29:17 +08:00
boos af05b40799 feat: Events API routes migrated to Rust 
- GET /api/events — list with filters (type, read, pagination)
- GET /api/events/count — unread count
- POST /api/events/{id}/read — mark one as read
- POST /api/events/read-all — mark all as read
- DELETE /api/events — clear all events
- Event model with sqlx FromRow
 2026-05-17 13:28:16 +08:00
boos 8568859da6 feat: User management + JWT auth routes 
- Admin users CRUD: /api/admin/users + /api/admin/users/{id}
- Public auth: /api/auth/register, /api/auth/login, /api/auth/me
- User model + password hashing via existing auth module
- JWT token generation and validation
- cargo check ✅ | cargo test 18/18 ✅
 2026-05-17 13:24:37 +08:00
boos 7987833ba9 feat: Rust refactor — full backend rewrite (Phases 1-6) 
Phase 1-3: Scaffold + types + auth (JWT, Argon2, API keys)
Phase 4a: Admin API (sites/accounts/tokens/downstream-keys/settings)
Phase 5: Proxy core (/v1/chat, /v1/images, /v1/models)
Phase 6: ComfyUI proxy routes migrated

- 80+ source files, all cargo check + 18 tests green
- Drop-in compatible with Node.js API surface
 2026-05-17 13:20:52 +08:00
boos ad0bb86e31 feat: ComfyUI embedded dev setup + proxy auth with downstream keys 
- COMFYUI_BASE configurable via env var (default 127.0.0.1:8188)
- All /api/comfyui/ routes protected by downstream API Key or admin token
- docker/Dockerfile.comfyui + docker-compose.comfyui.yml for dev
- npm scripts: comfyui:install, comfyui:start, comfyui:stop
- .gitignore / .env.example updated
 2026-05-17 13:04:46 +08:00
boos 2fe8d8528a fix: ComfyUI Agent uses upstream API via env vars 
- Read BOOSAPI_UPSTREAM_BASE/BOOSAPI_UPSTREAM_KEY from env
- Default to api.boos.lat/v1 with sk-boos4721
- Document: internal tool bypasses proxy /v1/ routing layer
- Update AGENTS.md with architecture decision
 2026-05-17 04:23:20 +08:00
boos 5e3d4ee7d4 refactor: ComfyUI Agent - fix auth, upstream API, and SSE streaming 
- Fix auth: use upstream API key (sk-boos4721) instead of local proxy
- Simplify SSE: remove nested SSE-in-SSE parsing, stream as plain text
- Fix frontend: add Authorization header from localStorage
- Fix ComfyUI nodes: default to api.boos.lat with correct API key
- All verified: frontend streaming works end-to-end with gpt-5.5
 2026-05-17 04:17:12 +08:00
boos b78b622f0c docs: add subagent team collaboration strategy to Rust plan 
Adds workstream map, parallel phase timing, shared contracts (AppState
extension, router composition, error type patterns), file ownership matrix,
subagent task template, git branch strategy, and coordinator workflow for
multi-agent parallel development.
 2026-05-16 11:27:42 +08:00
boos 56b57f7ace docs: add Rust backend rewrite plan 
Phase-by-phase migration plan for replacing the Node.js/Fastify backend
with Axum + SQLx + tokio in Rust. 13 phases covering scaffold through
integration testing.
 2026-05-16 11:26:12 +08:00
boos f0188d3f68 docs: update plan with deployment doc improvements 2026-05-16 00:59:36 +08:00
boos 5bd847dd06 docs: complete Docker deployment documentation 
- Fix all remaining metapi → boosapi references
- Full docker-compose.yml example with healthcheck
- .env file pattern with variable interpolation
- Complete environment variable reference table
- Docker Compose production checklist
- Redis/MySQL/PostgreSQL extension configs
- Resource limits example
- Nginx WebSocket support
- Admin panel IP restriction pattern
- Upgrade/rollback procedures with commands

Signed-off-by: Boos4721 <boos4721@icloud.com>
 2026-05-16 00:54:54 +08:00
boos 0106dd3f5d Full internal rename: metapi → boosapi 
Rename all remaining internal protocol identifiers:
- x-metapi-* headers → x-boosapi-*
- metapi: reasoning prefix → boosapi:
- __metapi* runtime markers → __boosapi*
- file-metapi-* → file-boosapi-*
- METAPI_* env vars → BOOSAPI_*
- metapi_turn_state/metapi_mcp_item__ etc. → boosapi_*
- package.json name → boosapi
- Docker/deploy/k3s/docs references

46 files changed, 168 insertions, 170 deletions.
typecheck:web passes (0 new errors).

Signed-off-by: Boos4721 <boos4721@icloud.com>
 2026-05-16 00:46:28 +08:00
boos d2c16c3919 docs: add plan/ directory with 2026-05-15 dev report 
- ComfyUI Agent conversational interface (SSE streaming)
- Metapi → BoosAPI full rebranding
- Gitea CI/CD runner on Alpine (OpenRC)
- Notification service architecture doc

Signed-off-by: Boos4721 <boos4721@icloud.com>
 2026-05-16 00:37:38 +08:00
boos 0f3ff82147 fix: restore ComfyUI as workflow frontend with BoosAPI backend integration 
ComfyUI is kept as a visual workflow editor (node-based). All actual
generation goes through BoosAPI's own API via boosapi_comfy_nodes.py
custom nodes (now defaulting to localhost:4000/v1).

Architecture:
  BoosAPI (Node.js, port 4000)
    ├── /video-agent → iframe → ComfyUI (Python, port 8188, CPU)
    │                              └── custom_nodes/boosapi_comfy_nodes.py
    │                                   └── calls BoosAPI /v1/... API
    ├── /comfyui-agent → chat interface (direct API calls)
    └── /v1/... → API endpoints (LLM, image, TTS, video)

Signed-off-by: boos <boos@boos.lat>
 2026-05-16 00:26:07 +08:00
boos bd06698c8e refactor: fully embed ComfyUI into BoosAPI, drop external dependency 
- Remove comfyui.ts (external proxy to ComfyUI at :8188)
- Remove videoAgent.ts (redundant with comfyuiAgent)
- Remove ComfyUI Python process from Dockerfile (CPU-only, useless)
- Update boosapi_comfy_nodes.py default to localhost BoosAPI
- Clean up index.ts, App.tsx, desktop.ts registrations
- Sidebar: merge '视频工作台'/'视频助手' into single '视频助手' entry

Signed-off-by: boos <boos@boos.lat>
 2026-05-16 00:21:18 +08:00
boos 9612bfcb3b chore: remove .github folder 
Signed-off-by: Boos4721 <boos4721@icloud.com>
 2026-05-16 00:17:00 +08:00
boos 48eb5bddf9 chore: remove CI entirely 
Signed-off-by: Boos4721 <boos4721@icloud.com>
 2026-05-16 00:15:23 +08:00
boos f92d0352a0 fix: lighter CI - single job, skip heavy builds, limit node memory
CI / Check (push) Failing after 14m24s
Signed-off-by: Boos4721 <boos4721@icloud.com>
 2026-05-16 00:05:15 +08:00
boos 2f9f3614a2 fix: adapt CI for Gitea Actions, remove Docker/GitHub-specific workflows
CI / Test & Check (push) Failing after 1h9m26s
CI / Schema Check (SQLite) (push) Failing after 14m50s
- Rewrite ci.yml: replace GitHub Actions with run: steps, drop
  Docker publish, MySQL/Postgres schema, and artifact upload jobs
- Delete codeql.yml (GitHub CodeQL, not available on Gitea)
- Delete docs-pages.yml (GitHub Pages specific)
- Delete release.yml (Docker Hub + GitHub Releases)
- Delete claude-code.md, claude-opus-4.7.md (unused)

Signed-off-by: Boos4721 <boos4721@icloud.com>
 2026-05-15 22:54:30 +08:00
boos cd42de2689 docs: add SaaS multi-tenant features and REST API overview 
- Add SaaS multi-tenant section to both Chinese and English READMEs
- Add REST API endpoint reference table
- Add SaaS/plan highlights in subtitle and pain-point table
- Bilingual sync

Signed-off-by: Boos4721 <boos4721@icloud.com>
 2026-05-15 22:35:16 +08:00
boos 7886a0ab8b feat: add SaaS multi-tenant user management
CI / Detect Docs Changes (push) Has been skipped
CI / Test Core (push) Failing after 30s
CI / Build Web (push) Failing after 1m44s
CI / Typecheck (push) Failing after 57s
CI / Repo Drift Check (push) Failing after 17s
CI / Schema Check (SQLite) (push) Failing after 18s
CI / Schema Check (MySQL) (push) Failing after 18s
CI / Schema Check (Postgres) (push) Failing after 17s
CI / Build Docs (push) Has been cancelled
CI / Publish Docker Image (armv7) (push) Has been cancelled
CI / Publish Docker Manifest (push) Has been cancelled
CI / Publish Docker Image (amd64) (push) Has been cancelled
CI / Build Server (push) Has been cancelled
CI / Build Desktop (push) Has been cancelled
CI / Audit Production Dependencies (push) Has been cancelled
CI / Publish Docker Image (arm64) (push) Has been cancelled
CodeQL / Analyze (JavaScript/TypeScript) (javascript-typescript) (push) Has been cancelled
- Add organizations, organization_members, invitations, data_plans tables
- Add organizationService (CRUD, member management, plan limit check)
- Add invitationService (create, accept, cancel invitations)
- Add planService (plan limits, seed defaults)
- Add /api/organizations/* routes (org CRUD, members, invitations)
- Add /api/invitations/* routes (public invite lookup, accept)
- Seed default plans (free/pro/enterprise) on startup

Signed-off-by: Boos4721 <boos4721@icloud.com>
 2026-05-15 21:25:53 +08:00
boos 07013e2a39 docs: highlight built-in ComfyUI features 
- Add ComfyUI chat assistant description in subtitle
- Add ComfyUI section in core features
- Update both Chinese and English versions

Signed-off-by: Boos4721 <boos4721@icloud.com>
 2026-05-15 20:58:29 +08:00
boos 2c4aabe961 docs: rewrite README for BoosAPI rebranding 
- Replace all Metapi references with BoosAPI
- Remove external service links (GitHub, Docker Hub, Render, Zeabur)
- Simplify structure for self-hosted deployment
- Update both Chinese and English versions

Signed-off-by: Boos4721 <boos4721@icloud.com>
 2026-05-15 20:51:10 +08:00
boos 9cfe8427b5 feat: rebrand Metapi to BoosAPI, add ComfyUI agent and user management
CI / Detect Docs Changes (push) Has been cancelled
CI / Test Core (push) Has been cancelled
CI / Build Web (push) Has been cancelled
CI / Build Server (push) Has been cancelled
CI / Build Desktop (push) Has been cancelled
CI / Typecheck (push) Has been cancelled
CI / Repo Drift Check (push) Has been cancelled
CI / Schema Check (SQLite) (push) Has been cancelled
CI / Schema Check (MySQL) (push) Has been cancelled
CI / Schema Check (Postgres) (push) Has been cancelled
CI / Build Docs (push) Has been cancelled
CI / Audit Production Dependencies (push) Has been cancelled
CI / Publish Docker Image (amd64) (push) Has been cancelled
CI / Publish Docker Image (arm64) (push) Has been cancelled
CI / Publish Docker Image (armv7) (push) Has been cancelled
CI / Publish Docker Manifest (push) Has been cancelled
CodeQL / Analyze (JavaScript/TypeScript) (javascript-typescript) (push) Has been cancelled
- Rename project from Metapi to BoosAPI across all UI and server strings
- Add ComfyUI conversational agent page (/comfyui-agent)
- Add user management system (register, login, API keys, admin)
- Update Dockerfile and database schema
- Add ComfyUI workflow nodes support
- Update shared contracts and platform configurations

Signed-off-by: Boos4721 <boos4721@icloud.com>
 2026-05-15 20:20:58 +08:00
Tursom K. Ulefits cdb12a9819 [codex] fix quota refresh probe model (#490)
CI / Detect Docs Changes (push) Has been cancelled
CI / Test Core (push) Has been cancelled
CI / Build Web (push) Has been cancelled
CI / Build Server (push) Has been cancelled
CI / Build Desktop (push) Has been cancelled
CI / Typecheck (push) Has been cancelled
CI / Repo Drift Check (push) Has been cancelled
CI / Schema Check (SQLite) (push) Has been cancelled
CI / Schema Check (MySQL) (push) Has been cancelled
CI / Schema Check (Postgres) (push) Has been cancelled
CI / Build Docs (push) Has been cancelled
CI / Audit Production Dependencies (push) Has been cancelled
CI / Publish Docker Image (amd64) (push) Has been cancelled
CI / Publish Docker Image (arm64) (push) Has been cancelled
CI / Publish Docker Image (armv7) (push) Has been cancelled
CI / Publish Docker Manifest (push) Has been cancelled
CodeQL / Analyze (JavaScript/TypeScript) (javascript-typescript) (push) Has been cancelled
Docs Pages / Build Docs (push) Failing after 2m53s
Docs Pages / Deploy Docs (push) Has been skipped
 2026-05-08 22:55:17 +08:00
Ju Zi f19ddac865 feat: 支持从站点页快捷添加 API Key (#505) 
Co-authored-by: juzi <956428403@qq.com>
 2026-05-08 22:54:40 +08:00
Cita 90e2f0c405 Merge PR #535: clear production dependency audit 
Merge the narrow package-lock refresh that restores the main production audit gate.
 2026-05-08 17:39:42 +08:00
cita-777 0f51dec36e Clear the main-branch production audit gate 
Constraint: main push CI fails on npm audit --omit=dev --audit-level=high after recent merges.
Rejected: Broad npm audit fix output | it updated unrelated dev-only lockfile entries.
Confidence: high
Scope-risk: narrow
Directive: Keep PR audit informational until production dependencies are audited on dev/main consistently.
Tested: ELECTRON_SKIP_BINARY_DOWNLOAD=1 npm ci --prefer-offline --no-audit --no-fund; npm audit --omit=dev --audit-level=high; npm run typecheck:server; npm test -- --run src/server/config.test.ts src/server/settingsRoutePayloads.test.ts
Not-tested: Full GitHub Actions matrix before opening PR.
 2026-05-08 17:35:24 +08:00
Cita f4148675e1 Merge PR #510: per-site model probe 
Merged after updating the PR onto current main and fixing the remaining probe-setting review gaps.\n\nValidation:\n- GitHub checks all passing: Test Core, Typecheck, Build Web/Server/Desktop, Repo Drift Check, Schema SQLite/MySQL/Postgres, CodeQL, CodeRabbit.\n- Local: npm run typecheck\n- Local: npm run repo:drift-check\n- Local: npx vitest run --root . src/server/db/schemaContract.test.ts src/server/db/schemaArtifactGenerator.test.ts src/server/db/schemaIntrospection.test.ts src/server/db/schemaParity.test.ts src/web/api.test.ts src/web/pages/helpers/sitesEditor.test.ts src/web/pages/sites.disabled-models-save.test.tsx src/web/pages/sites.edit-scroll.test.tsx
 2026-05-08 16:58:27 +08:00
cita-777 e5a8a0b3d7 Keep per-site probe settings reliable before merge 
Refresh the PR onto current main and close the remaining probe-setting review gaps: the primary site save now persists the latency threshold, the site row type carries that field without an any-cast, active probe streams are aborted on unmount, and all-model one-shot probes get the longer timeout they need.

Constraint: PR #510 must preserve the per-site model probe feature while merging cleanly into current main.
Rejected: Leave threshold persistence behind the separate probe-settings button | the primary save path would still silently drop user changes.
Rejected: Keep the SiteRow any-cast | it hides API/schema drift for the new persisted field.
Confidence: high
Scope-risk: narrow
Directive: Keep probe setting fields represented in the typed site save payload and covered by focused web API/editor tests.
Tested: npm run typecheck; npm run repo:drift-check; npx vitest run --root . src/server/db/schemaContract.test.ts src/server/db/schemaArtifactGenerator.test.ts src/server/db/schemaIntrospection.test.ts src/server/db/schemaParity.test.ts src/web/api.test.ts src/web/pages/helpers/sitesEditor.test.ts src/web/pages/sites.disabled-models-save.test.tsx src/web/pages/sites.edit-scroll.test.tsx
Not-tested: Full npm test.
 2026-05-08 16:51:05 +08:00
Cita 1d61a7ac84 Merge PR #495: auto-discover recent Docker Hub dev tags 
Merged after resolving conflicts with current main.\n\nValidation:\n- GitHub checks all passing: Test Core, Typecheck, Build Web/Server/Desktop, Repo Drift Check, Schema checks, CodeQL, CodeRabbit.\n- Local: npx vitest run --root . src/web/pages/settings/UpdateCenterSection.test.tsx src/server/services/updateCenterVersionService.test.ts src/server/routes/api/updateCenter.test.ts src/server/services/updateCenterStatusService.test.ts\n- Local: npm run typecheck\n- Local: npm run repo:drift-check
 2026-05-08 16:27:26 +08:00
cita-777 93bc42a69d Refresh the recent Docker tag PR onto current main 
The release branch had fallen behind current main and only conflicted in the
Update Center recent-tag test. Keep the latest main-side deploy-state coverage
while preserving the PR's raw-tag filtering and digest visibility assertions.

Constraint: PR #495 must merge into the current main without widening the PR diff beyond the update-center candidate behavior.
Rejected: Drop the PR-specific digest/raw-tag assertions | would regress the review fixes that prompted the branch update.
Confidence: high
Scope-risk: narrow
Directive: Keep recent Docker tag cards deployable only from real tagName values and keep digest metadata visible before deployment.
Tested: npx vitest run --root . src/web/pages/settings/UpdateCenterSection.test.tsx src/server/services/updateCenterVersionService.test.ts src/server/routes/api/updateCenter.test.ts src/server/services/updateCenterStatusService.test.ts; npm run typecheck; npm run repo:drift-check; git diff --cached --check origin/main
Not-tested: Full npm test.
 2026-05-08 16:23:05 +08:00
Cita 508fa71ec7 Merge pull request #518 from kevinye13/fix/settings-allowlist-json-array 
fix(settings): persist model allowlist as JSON array
 2026-05-08 16:05:15 +08:00
Cita 3ce705ab9d Update contributors section in README.md 2026-05-08 15:37:37 +08:00
Cita 4481cf7493 Clean up contributor section in README 
Removed unnecessary contributor images from the README.
 2026-05-08 15:29:19 +08:00
Cita 3720b3d0ed Merge pull request #533 from cita-777/release/fix-protocol-compatibility-20260508 
[fix] Harden protocol compatibility from dev
 2026-05-08 11:05:31 +08:00
cita-777 10dc1ba7bd Carry update center review test follow-up 
This merge keeps PR #533 aligned with dev after addressing CodeRabbit follow-up test comments. The changes are limited to UpdateCenterSection test assertions.

Constraint: Release branch remains the publication branch for the open main-targeting PR.

Confidence: high

Scope-risk: narrow

Tested: npx vitest run --root . src/web/pages/settings/UpdateCenterSection.test.tsx

Tested: npm run typecheck:web

Co-authored-by: OmX <omx@oh-my-codex.dev>
 2026-05-08 10:50:25 +08:00
cita-777 fee6a6388f Tighten update center review test coverage 
CodeRabbit follow-up review pointed out that one renderer assertion could not fail usefully and that the new recent-candidate deploy test did not prove log streaming after dispatch. The test now asserts the visible candidate text directly and covers streamUpdateCenterTaskLogs for the new deploy path.

Constraint: Keep review follow-up scoped to test coverage only.

Confidence: high

Scope-risk: narrow

Tested: npx vitest run --root . src/web/pages/settings/UpdateCenterSection.test.tsx

Tested: npm run typecheck:web

Co-authored-by: OmX <omx@oh-my-codex.dev>
 2026-05-08 10:50:10 +08:00
cita-777 00348e0528 Carry protocol review fixes into release 
The release branch is main-based and tracks the reviewed dev slice for PR publication. This merge carries the post-review compatibility fixes without rewriting the already-open PR history.

Constraint: PR #533 publishes dev changes through a clean release branch targeting main.

Rejected: Recreate the PR branch from scratch | unnecessary churn after green checks and review context already exist.

Confidence: high

Scope-risk: narrow

Tested: npx vitest run --root . src/server/proxy-core/responsesPreflight.test.ts src/server/proxy-core/serviceTierPolicy.test.ts src/server/routes/proxy/chat.stream.test.ts src/web/pages/settings/UpdateCenterSection.test.tsx

Tested: npm run typecheck:server

Tested: npm run typecheck:web

Tested: npm run repo:drift-check

Co-authored-by: OmX <omx@oh-my-codex.dev>
 2026-05-08 10:43:12 +08:00
cita-777 8309ac073a Close protocol compatibility review gaps 
Review feedback found narrow compatibility regressions in the web-search shim, Responses tool detection, service tier accounting, and update-center Docker candidate actions. The fix keeps synthetic search routed through the dedicated search model, preserves Responses text compatibility, distinguishes absent service_tier from filtered service_tier, and evaluates recent Docker tags per candidate.

Constraint: Review fixes must stay on dev first, then flow into the main-based release PR branch.

Rejected: Leave Responses web_search simulation on the request model | it has the same search-route selection risk as Anthropic simulation.

Confidence: high

Scope-risk: narrow

Tested: npx vitest run --root . src/server/proxy-core/responsesPreflight.test.ts src/server/proxy-core/serviceTierPolicy.test.ts src/server/routes/proxy/chat.stream.test.ts src/web/pages/settings/UpdateCenterSection.test.tsx

Tested: npm run typecheck:server

Tested: npm run typecheck:web

Tested: npm run repo:drift-check

Co-authored-by: OmX <omx@oh-my-codex.dev>
 2026-05-08 10:42:49 +08:00
cita-777 207ab5cedf Prepare protocol compatibility release 2026-05-08 00:32:50 +08:00
cita-777 2491a9af5a Harden cross-protocol request compatibility 
Several downstream clients send non-cache compatibility fields across Chat, Responses, Anthropic Messages, and Responses WebSocket surfaces. The proxy now normalizes legacy functions/function_call, maps web_search tools across protocols, rejects unsupported HTTP Responses continuation shapes before upstream dispatch, and applies configurable service_tier policy consistently before requests leave the server.

Constraint: Publication flow keeps day-to-day commits on dev and opens main PRs from a release branch.

Constraint: No new dependencies; web_search-only simulation reuses the existing local search route.

Rejected: Forward external HTTP previous_response_id to strict upstreams | it produces ambiguous continuation failures and stale retry behavior outside WebSocket state.

Rejected: Add a dedicated search dependency | existing /v1/search route is sufficient for synthetic server-tool responses.

Confidence: high

Scope-risk: moderate

Directive: Keep Responses HTTP continuation checks aligned with WebSocket continuation support before relaxing these guards.

Tested: npm run typecheck:server

Tested: npx vitest run --root . src/server/proxy-core/responsesPreflight.test.ts src/server/proxy-core/serviceTierPolicy.test.ts src/server/test-fixtures/protocol/non-cache-field-matrix.test.ts src/server/transformers/openai/responses/conversion.test.ts src/server/transformers/anthropic/messages/conversion.test.ts src/server/routes/proxy/chat.stream.test.ts src/server/routes/proxy/responses.codex-oauth.test.ts

Tested: npx vitest run --root . src/server/routes/proxy/responses.websocket.test.ts

Tested: npm run repo:drift-check

Not-tested: Full application build and full Vitest suite

Co-authored-by: OmX <omx@oh-my-codex.dev>
 2026-05-08 00:30:48 +08:00
kevinye13 a53c62885b fix(settings): persist model allowlist as JSON array 2026-04-27 20:35:18 +08:00
Xiang Li 99392341fe fix: handle empty-string column defaults in MySQL schema introspection 
MySQL information_schema.COLUMNS.COLUMN_DEFAULT stores DEFAULT '' as an
empty string, not NULL. normalizeDefaultValueForColumn was treating any
empty rawDefaultValue as 'no default' and returning null, causing the
MySQL schema parity test to see defaultValue: null for post_refresh_probe_model
while schemaContract.json (generated from TypeScript schema) had "''".

Fix: when rawDefaultValue is empty string, return "''" for text/json columns
instead of null, so the round-trip through MySQL introspection matches the
contract.
 2026-04-23 23:46:10 +08:00
Xiang Li 078ac4aa9d fix: add statement-breakpoint to migration 0025 and regenerate upgrade SQL 
Better-SQLite3 requires --> statement-breakpoint between each statement
in a migration file; without it all statements are passed as a single
string to Database.prepare() which throws RangeError on multi-statement input.
 2026-04-23 23:21:58 +08:00
Xiang Li cb5078468c fix: address CodeRabbit review for per-site probe 
- Fix SSE abort: propagate AbortSignal to worker pool; close connection
  immediately on client disconnect without sending 'complete' event
- Fix Boolean coercion: use strict === true/=== 1 check instead of Boolean()
  to avoid Boolean('false') === true foot-gun
- Fix probe-now: parse and forward latencyThresholdMs from request body
- Fix api.ts probeSiteNow: add latencyThresholdMs to options type
- Fix backup import: restore postRefreshProbe* fields when inserting sites
  so that backup/restore round-trips preserve per-site probe config
- Fix latency threshold persistence: add postRefreshProbeLatencyThresholdMs
  column (migration 0026), save/load it in site editor, pass to
  runPostRefreshProbeIfEnabled so auto-probe also respects the threshold
- Fix state management: setProbeCompleted(false) at probe start; error
  branch also refreshes model lists and sets probeCompleted to show results
- Regenerate schema artifacts (mysql/postgres bootstrap+upgrade, contract)
 2026-04-23 23:08:50 +08:00
Xiang Li 37924751f6 chore(db): add migration and regenerate schema artifacts for per-site probe columns 
- Add drizzle/0025_site_post_refresh_probe.sql (ALTER TABLE sites ADD 3 columns)
- Update drizzle/meta/_journal.json (idx=24 entry)
- Regenerate mysql/postgres bootstrap+upgrade SQL and schemaContract.json
 2026-04-23 22:50:57 +08:00
Xiang Li 46f23ddbb3 feat(sites): per-site model probe with streaming logs and auto-disable 
- Move post-refresh probe settings from global config to per-site (sites table)
- Add manual 'probe now' button in site editor with real-time SSE log stream
- Use fetch+ReadableStream instead of EventSource to support Authorization header
- Concurrent probe execution (default 10 workers) via worker-pool pattern
- Add stop button to cancel in-flight probe while preserving completed results
- Add latency threshold: auto-disable models exceeding response time limit
- Treat inconclusive probe results as unsupported (auto-disable)
- Show specific failure reason in logs (timeout, no token, model not found, etc.)
- Refresh and display post-probe model status list (green=available, red=disabled)
- Remove probe settings from global Settings page and RuntimeSettingsPayload
 2026-04-23 21:42:48 +08:00
cita-777 fa6edec83a Keep recent Docker tag deploys explicit and tag-safe 
Review feedback pointed out two small but important operator-facing gaps in the
recent-tag card: one-click deploy should only be available when a real raw
Docker tag exists, and the digest that will be deployed should be visible on
the card instead of remaining implicit. This patch tightens the candidate
filter to require tagName and renders the digest metadata before the deploy
actions, with regression coverage for both behaviors.

Constraint: The deploy API still requires a raw Docker tag, not a normalized display value
Constraint: The recent-tag card should surface the exact digest operators are about to deploy
Rejected: Keep accepting normalizedVersion-only candidates | could enable one-click deploy with a non-tag display value
Rejected: Rely on displayVersion alone for digest visibility | digest presence should stay explicit even if display text changes later
Confidence: high
Scope-risk: narrow
Reversibility: clean
Directive: Any future recent-tag UI should treat tagName as the deployable identity and digest as separately visible metadata
Tested: src/web/pages/settings/UpdateCenterSection.test.tsx, npm run typecheck, git diff --check
Not-tested: Full PR checks rerun pending after push
 2026-04-18 16:09:24 +08:00
cita-777 93912bb330 Publish the dev-tag discovery upgrade to main on a clean release branch 
This release branch snapshots the latest dev work onto current main so the
update center can surface recent non-stable Docker tags without operators
looking them up manually. The branch keeps stable Docker discovery as the
primary path while carrying the new recent-tag auto-discovery, UI affordances,
and regression coverage through the repo's release flow.

Constraint: Publication must start from latest origin/main and merge origin/dev on a clean release branch
Constraint: Stable Docker Hub discovery semantics must remain intact while adding recent non-stable discovery
Rejected: Re-open or reuse the already-merged PR #494 branch | it has already been absorbed by main and deleted remotely
Rejected: Publish directly from dev | repo workflow requires a clean release branch to main
Confidence: high
Scope-risk: moderate
Reversibility: clean
Directive: Keep future dev-tag publication work on fresh release branches cut from origin/main; do not revive merged release branches
Tested: Focused update-center vitest suite, npm run typecheck, npm run repo:drift-check, npm run build:web, npm run docs:build, git diff --check (release branch)
Not-tested: Full npm test remains red because tmp/sub2api frontend suites are still broken in this repo snapshot
 2026-04-18 15:32:44 +08:00
cita-777 c94e3148dd Let operators deploy recent dev Docker tags without manual lookup 
The update center already allowed manual Docker tag deploys, but operators
still had to know and paste dev or branch tags by hand. This change keeps the
stable Docker Hub candidate as the main path while automatically surfacing the
most recent non-stable tags and their digests for one-click deployment.

Constraint: Stable Docker Hub discovery must remain the default candidate path
Constraint: Existing deploy API and helper protocol should stay unchanged
Rejected: Promote dev tags into the primary stable candidate slot | would blur stable and experimental release semantics
Rejected: Add a brand new backend deploy endpoint for recent tags | existing targetTag/targetDigest deploy path already covers the need
Confidence: high
Scope-risk: moderate
Reversibility: clean
Directive: Keep stable and recent non-stable Docker tag discovery distinct unless product semantics deliberately change
Tested: Focused vitest for update-center services/routes/UI, npm run typecheck, npm run repo:drift-check, npm run build:web, npm run docs:build, git diff --check
Not-tested: Full npm test remains red because tmp/sub2api frontend suites are still broken in this repo snapshot
 2026-04-18 15:28:03 +08:00
Cita 262651a708 Merge pull request #494 from cita-777/release/feat-update-center-dev-tags-20260417 
[chore] publish dev snapshot to main
 2026-04-18 14:30:53 +08:00
cita-777 4a57e312f5 Align outbound fallback expectations with the reviewed Responses id shape 
The last CI failure after the review cleanup was only a stale test expectation:
function_call fallback items now correctly use fc_* item ids while preserving the
call_* id in call_id. Updating the test keeps the suite aligned with the
Responses payload shape we intentionally adopted in the bridge.

Constraint: Keep the fix to the assertion only; the production behavior already matches the reviewed contract
Rejected: Revert the fc_* item id change | that would reopen the review thread we intentionally fixed
Confidence: high
Scope-risk: narrow
Directive: When bridge output semantics change intentionally, update sibling facade tests in the same PR so CI reflects the new contract immediately
Tested: Focused vitest for openai responses outbound/response bridge, Gemini request bridge, Settings payload rules; typecheck; git diff --check
Not-tested: Full npm test
 2026-04-18 14:13:20 +08:00
cita-777 544324ed0a Restore the full payload-rule protocol list in Settings 
One last review thread caught a real UI regression: the visual payload-rule
editor had drifted away from the shared protocol option source and no longer
exposed several active platform targets. Rebinding the dropdown to the shared
option list fixes the regression without inventing another source of truth.

Constraint: The fix should reuse the existing shared option list instead of creating another hardcoded protocol subset
Rejected: Expand the inline array manually | would repeat the same drift problem that caused the regression
Confidence: high
Scope-risk: narrow
Directive: Payload-rule protocol selectors should always read from the shared option source so Settings and the payload-rule parser stay aligned
Tested: settings.payload-rules vitest; typecheck; git diff --check
Not-tested: Full npm test
 2026-04-18 14:01:26 +08:00
cita-777 1f464dc03d Close out the last review edge-cases before final merge 
The remaining review threads were down to route alias hygiene, proxy-safe header
ordering, and a Gemini canonical tool-result mismatch. This commit makes the
alias/websocket behavior explicit, preserves contributor helper safety, and
teaches the canonical Gemini path to recover tool names and wrap function
results the same way the OpenAI-shaped path already does.

Constraint: Keep the last review fixes limited to the current branch so the release PR stays easy to reason about
Rejected: Defer the Gemini canonical fix to a later refactor | the review found a real functional mismatch and the fix stayed localized to the request bridge
Confidence: high
Scope-risk: narrow
Directive: Keep canonical-to-provider bridges internally consistent; if one path resolves tool names or wraps results, the sibling path should not diverge silently
Tested: Focused vitest for Gemini request bridge, route aliases, upstream request builder, responses response bridge, contributor updater; typecheck; git diff --check
Not-tested: Full npm test; any broader end-to-end Gemini live-provider behavior outside the covered bridge tests
 2026-04-18 13:46:57 +08:00
cita-777 20f06d391c Tighten alias and header edge-cases called out in review 
The latest review pass found a few more concrete edge-cases that were still
cheap to close: invalid /responses aliases could still rewrite typos, websocket
session headers should prefer proxy-safe dashed forms, contributor rendering
needed an input guard, and several upstream request/response helpers still had
small contract mismatches around Accept/beta handling and synthesized tool ids.
These fixes keep the release branch behavior explicit while the PR remains open.

Constraint: Keep changes surgical and well-covered so the review cleanup does not destabilize the already-green release branch
Rejected: Leave these for post-merge cleanup | they were still active review threads with straightforward fixes
Confidence: high
Scope-risk: narrow
Directive: When alias routes exist only for ergonomics, reject unknown subpaths loudly instead of silently rewriting them
Tested: Focused vitest for contributor updater, route aliases, upstream request builder, openai responses response bridge; typecheck; git diff --check
Not-tested: Full npm test; the remaining Gemini review thread that likely needs a broader canonical-tool-result contract decision
 2026-04-18 13:38:46 +08:00
cita-777 e795f22367 Settle the last concrete review regressions on the release branch 
A few review threads still pointed at real behavior mismatches: Anthropic tool
JSON deltas were still trimming whitespace, Responses conversion still raised
low token caps to the floor, and the bare /responses GET alias returned upgrade
messaging that did not match the actual websocket entrypoint. This commit makes
those behaviors explicit and locks them with focused tests.

Constraint: Keep the release branch green while fixing only the review findings that have a clear, testable contract
Rejected: Leave these for a follow-up cleanup PR | they were low-diff and directly blocked comment resolution on the current release PR
Confidence: high
Scope-risk: narrow
Directive: Preserve raw stream delta text unless a downstream protocol explicitly requires normalization; whitespace can be semantic in incremental payloads
Tested: Focused vitest for anthropic stream bridge, responses conversion, route aliases; typecheck; git diff --check
Not-tested: Full npm test; the remaining review threads that still need broader product decisions
 2026-04-18 13:28:50 +08:00
cita-777 02520255db Clear remaining low-risk review debt on the release branch 
The PR still had a few targeted review threads around contributor pagination,
route-layer passthroughs, dead header fallbacks, and synthetic response ids.
These are small enough to settle directly on the release branch without
broadening the merge scope, and they tighten the repo back toward the
service-owned boundaries this refactor is aiming for.

Constraint: Keep the changes narrow and regression-covered so the release PR stays green while review threads are closed out
Rejected: Leave the minor threads for follow-up after merge | they were isolated enough to fix now and would keep noise on the PR
Confidence: high
Scope-risk: narrow
Directive: When a route shim stops serving any route-local behavior, point callers at the owning service instead of keeping a passthrough around
Tested: Focused vitest for contributor updater, openai responses response bridge, upstream request builder, stats proxy logs, architecture boundaries; typecheck; repo drift check; git diff --check
Not-tested: Full npm test; unresolved review threads that still require larger product decisions
 2026-04-18 13:19:29 +08:00
cita-777 4b5d045b00 Address high-priority review gaps before merging the dev snapshot 
The release branch still had unresolved review comments around payload-rule
atomicity, brand blocking, compact fallback controls, and response
compatibility edge-cases. This patch pulls those behaviors back in line with
the intended contracts and adds focused regression coverage for the fragile
bridges.

Constraint: The fixes must stay narrow to the PR branch so review/merge can continue without reopening the larger dev snapshot conflict set
Rejected: Leave outdated-looking threads unresolved until after merge | reviewers still see concrete unfixed regressions in the current release branch
Rejected: Re-run another broad merge from dev/main | too risky while the PR branch is already green and mergeable
Confidence: medium
Scope-risk: moderate
Directive: If these release-branch fixes need to persist for future release cuts, backport them onto dev instead of re-fighting the same review threads next time
Tested: Focused vitest for settings events, brand matcher, compact responses, codex compatibility, anthropic stream bridge, openai chat response bridge; typecheck; repo drift check; git diff --check
Not-tested: Full npm test; live PR thread resolution state after push
 2026-04-18 13:05:52 +08:00
cita-777 57db7fd107 Keep PR audit informational without leaving the check red 
The CI workflow already described production dependency audit as an
informational PR signal, but the job still surfaced as a failing check.
That left release PRs in an unstable state even after the real merge-gate
jobs were green. This keeps PR audits visible as warnings while still
letting main-branch pushes fail if production dependency audit actually
returns a non-zero exit.

Constraint: Preserve production audit visibility while avoiding false-red PR status
Rejected: Remove audit from CI entirely | loses vulnerability visibility
Confidence: high
Scope-risk: narrow
Reversibility: clean
Directive: Keep audit informational on pull requests unless branch protection is intentionally tightened later
Tested: YAML parse via ruby; git diff --check
Not-tested: Full GitHub Actions rerun pending after push
 2026-04-17 23:36:51 +08:00
cita-777 4aa888e581 Repair release-branch CI after folding dev onto main 
The release branch inherited a few merge-shaped regressions after the
large dev snapshot was layered onto the latest main snapshot. This
commit restores the main-compatible stats and TokenRoutes behavior the
CI suite expects and adds the missing multi-brand helper export so the
release branch reflects a coherent post-merge tree instead of a
partially regressed hybrid.

Constraint: Must keep the release branch mergeable to main while preserving the current publish snapshot shape
Rejected: Re-open the whole release merge and hand-resolve every file again | too broad for targeted CI repair
Confidence: medium
Scope-risk: narrow
Reversibility: clean
Directive: When dev and main have drifted heavily, re-run the main-facing CI tests after any conflict normalization pass
Tested: targeted vitest suite for failing CI jobs plus update-center coverage; typecheck
Not-tested: Full npm test still not representative locally because of unrelated untracked tmp/sub2api suites outside the PR branch content
 2026-04-17 23:26:22 +08:00
cita-777 f335a330e3 Prepare the dev snapshot for main review on a clean release branch 
This release branch starts from the latest origin/main and folds in the
current origin/dev snapshot so the PR to main can follow the repo's
publish flow without opening directly from dev. Conflict-heavy files
were normalized back to the dev snapshot where necessary so the release
branch reflects the code currently being carried on dev instead of a
line-merged hybrid.

Constraint: Publication flow requires a clean release branch from latest origin/main rather than a PR directly from dev
Constraint: The branch must preserve the current dev snapshot even when main and dev have drifted substantially
Rejected: Open the PR directly from dev | violates the repo publication flow
Rejected: Manually redesign every historic dev/main conflict during release prep | too broad for a publish branch
Confidence: medium
Scope-risk: moderate
Reversibility: clean
Directive: Treat this branch as a publication snapshot of dev-on-top-of-main, not as a general cleanup pass over old divergence
Tested: update-center focused vitest suite on release branch; typecheck; build:web; docs:build; repo:drift-check
Not-tested: Full npm test remains red from inherited tmp/sub2api frontend suites and an existing firstByteTimeout unhandled error
 2026-04-17 22:58:06 +08:00
cita-777 87fb5149e6 Let operators deploy dev Docker Hub tags from the update center 
The update center previously surfaced stable Docker Hub candidates but
left dev and branch-tag rollouts stranded in SSH and Helm commands.
This adds a repo-native manual Docker tag entrypoint in Settings so
operators can deploy dev, branch, temporary, or sha tags through the
existing helper flow without changing the backend deploy contract.

Constraint: Keep the existing helper API and digest-aware Helm contract unchanged
Constraint: Preserve stable Docker Hub candidate discovery for default reminders
Rejected: Expand automatic Docker Hub discovery to all branch tags | would blur stable release reminders with operator-only rollout targets
Confidence: high
Scope-risk: narrow
Reversibility: clean
Directive: Keep automatic candidate detection stable-first; manual tag deploy is the escape hatch for non-stable tags
Tested: update-center focused vitest suite; typecheck; build:web; docs:build; repo:drift-check
Not-tested: Full npm test remains red due to unrelated tmp/sub2api frontend suites and an existing firstByteTimeout unhandled error
 2026-04-17 22:43:47 +08:00
cita-777 f67ade2e59 Keep dev green after moving the active worktree snapshot 
The transferred dev snapshot was not publication-ready yet: full tests still
failed because worktree-local docs resolution assumed a repo-root node_modules
tree, some protocol expectations no longer matched the refactored request
bridges, oauth/account-token route tests reused stale modules after resetting
DATA_DIR, and model discovery still fired unawaited default-token writes.

This follow-up makes the moved dev branch self-consistent and green again by
stabilizing module/test isolation, awaiting token mirroring writes, and
aligning narrow tests with the current transformer and request-builder
contracts.

Constraint: The fix set had to stay narrow and unblock the new dev branch without reworking the broader transferred refactor
Rejected: Revert the transferred snapshot | would lose the user's requested dev-branch continuation point
Confidence: medium
Scope-risk: moderate
Reversibility: clean
Directive: If more DATA_DIR-scoped API test files start flaking under shared workers, reset modules before importing singleton db/config modules instead of relying on process env mutation alone
Tested: git diff --check; npm run typecheck; npm run repo:drift-check; npm test
Not-tested: Live OAuth/provider flows outside the mocked test harness
 2026-04-17 19:59:14 +08:00
cita-777 88f40e91f7 Preserve the active worktree snapshot on dev for follow-on integration 
The root checkout already contained a large in-progress proxy, transformer,
and settings refactor. This commit captures that exact work on a dedicated
local dev branch without disturbing the original dirty worktree, so the
changes can be continued or split from dev instead of living only as
uncommitted state.

Constraint: The source checkout was already dirty on another branch, so the move had to preserve that worktree while excluding local .idea and .omx residue from the commit
Rejected: Switch the dirty root checkout directly to dev | risked disrupting the original branch and in-progress state
Confidence: medium
Scope-risk: broad
Reversibility: clean
Directive: Treat this as a transfer snapshot; fix the failing oauth/accountTokens/normalized/docs test regressions before merge or publication
Tested: git diff --check; npm run typecheck; npm run repo:drift-check
Not-tested: Clean test pass; npm test currently fails in oauth routes, accountTokens sync, shared normalized helpers, gemini route expectations, architecture-boundaries, and docs vitepress config
 2026-04-17 19:41:14 +08:00
Cita a2c2ae614a [codex] expose more payload-rule upstream types (#474) 
* Expose more payload-rule upstream types in Settings

The first payload-rules UI only offered a narrow set of protocol labels, which
made live troubleshooting confusing once real playground traffic routed through
platforms like sub2api instead of codex. This expands the selectable upstream
types, extracts the option list into one small helper, and renames the field to
上游类型 so the UI matches what the runtime matcher actually uses.

Constraint: Must preserve the existing payload-rules schema key (`protocol`) even though the UI wording is now upstream-type oriented
Rejected: Leaving the dropdown codex/openai-only and telling operators to hand-edit JSON | too easy to misconfigure during live routing diagnosis
Confidence: high
Scope-risk: narrow
Reversibility: clean
Directive: If new canonical site platforms are added, update payloadRuleProtocolOptions.ts so the visual editor stays aligned with runtime matching
Tested: npx vitest run --root . src/web/pages/settings.payload-rules.test.tsx src/web/pages/settings.payload-rule-platform-options.test.ts
Tested: npm run typecheck:web
Tested: npm run typecheck:web:test
Tested: npm run repo:drift-check
Not-tested: Manual dropdown interaction in a browser

* Keep payload-rule upstream types aligned with one-api backend support

Code review caught that the visual editor still omitted one-api even though the
backend continues to treat it as a valid upstream platform. This adds the
missing option and extends the focused option-set test so operators can create
payload rules for one-api without dropping to raw JSON.

Constraint: Must preserve the runtime payload-rules schema and only close the UI/backend option gap
Rejected: Removing one-api from the backend in this PR | unrelated behavioral change and broader migration risk
Confidence: high
Scope-risk: narrow
Reversibility: clean
Directive: When backend platform support changes, update payloadRuleProtocolOptions.ts and its focused test in the same PR
Tested: npx vitest run --root . src/web/pages/settings.payload-rules.test.tsx src/web/pages/settings.payload-rule-platform-options.test.ts
Tested: npm run typecheck:web
Tested: npm run typecheck:web:test
Tested: npm run repo:drift-check
Not-tested: Manual browser check of the expanded dropdown list
 2026-04-10 16:13:56 +08:00
Cita 9c766dec1c [codex] add payload rules settings UI (#473) 
* Make payload request overrides configurable from Settings

The payload-rules engine already existed in the proxy path, but operators had
no supported runtime UI to manage CPA-style overrides. This wires the setting
through the runtime settings API, adds strict validation, and ships a
low-friction visual editor with an advanced JSON fallback so common cases like
Codex high reasoning can be configured without hand-editing backend state.

Constraint: Must reuse the existing payload-rules execution path and settings table without schema changes
Constraint: Must fit the existing metapi Settings-page patterns rather than introducing a standalone config surface
Rejected: JSON-only editor as the primary UX | too long and too easy to misconfigure for common cases
Rejected: A brand-new backend rule format for the UI | would duplicate the existing payload-rules source of truth
Confidence: high
Scope-risk: moderate
Reversibility: clean
Directive: Keep visual-rule serialization and advanced JSON editing in sync before extending the rule model
Tested: npm run typecheck
Tested: npx vitest run --root . src/server/services/payloadRules.test.ts src/server/routes/api/settings.events.test.ts src/web/pages/settings.payload-rules.test.tsx
Tested: npm run repo:drift-check
Not-tested: Manual browser interaction smoke on the Settings page in this clean PR worktree

* Prevent payload-rules saves from violating review expectations

Code review surfaced two operator-facing edge cases in the first payload-rules
PR: successful rule parsing could still be committed before a later validation
error, and visual edits could silently overwrite unsaved advanced JSON. This
stages payload-rules until the request finishes validating and adds an explicit
confirmation gate before visual actions discard unsynced advanced edits.

Constraint: Keep the fix narrow to the reviewed payload-rules feature without refactoring unrelated runtime-settings atomicity behavior
Rejected: Silently skipping draft resync while keeping visual edits active | would leave save semantics ambiguous when advanced JSON stays dirty
Confidence: high
Scope-risk: narrow
Reversibility: clean
Directive: If the settings endpoint ever moves toward full request atomicity, re-check this staged payload-rules write path against the broader strategy
Tested: npm run typecheck
Tested: npx vitest run --root . src/server/routes/api/settings.events.test.ts src/web/pages/settings.payload-rules.test.tsx
Tested: npm run repo:drift-check
Not-tested: Manual browser smoke of the confirmation dialog text
 2026-04-10 14:27:43 +08:00
Cita 2f774e204c Keep MySQL usage aggregation from crashing startup (#471) 
The usage aggregation projector was written with SQLite/Postgres conflict builders, but Render can switch the runtime DB to MySQL from saved settings. That made the startup scheduler throw before the service stayed healthy.

This change branches the projector's checkpoint and aggregate writes to MySQL-safe onDuplicateKeyUpdate calls while preserving the existing SQLite/Postgres onConflict behavior. A mocked MySQL regression test now omits the onConflict builders entirely so future regressions fail fast.

Constraint: Drizzle conflict APIs are dialect-specific and the projector starts during boot

Rejected: Disable the projector on MySQL | would keep admin analytics stale and hide the real incompatibility

Confidence: high

Scope-risk: narrow

Reversibility: clean

Directive: New usage-aggregation writes must branch on runtimeDbDialect before using conflict helpers

Tested: npx vitest run --root . src/server/services/usageAggregationService.test.ts src/server/services/usageAggregationService.mysql.test.ts

Tested: npm run typecheck:server

Tested: npm run repo:drift-check

Tested: npm run build:server

Not-tested: Live MySQL projector pass against a deployed runtime database
 2026-04-10 12:41:08 +08:00
Cita 8cf78a5354 [codex] smooth route detail panel motion (#467) 
* Keep route-detail motion smooth while restoring a more panel-like reveal feel

The route page detail panel originally reused the shared collapse container,
which looked lively but reintroduced layout-heavy motion inside the desktop
route grid. This change keeps the non-layout presence shell, then tunes the
panel animation itself so it reveals from the top with a softer, more
trace-panel-like feel without falling back to grid row interpolation.

Constraint: The desktop route detail panel sits inside a multi-column CSS grid and must avoid layout-driven collapse animation
Rejected: Reuse anim-collapse exactly as ProxyLogs does | reopening grid-template-rows animation brought back jank on route expand/collapse
Confidence: high
Scope-risk: narrow
Reversibility: clean
Directive: Preserve transform/clip-path-based motion here unless grid placement is redesigned; do not reintroduce layout collapse without profiling
Tested: npm test -- src/web/pages/tokenRoutes.desktop-detail-panel.test.tsx src/web/pages/tokenRoutes.group-collapse.test.tsx src/web/pages/token-routes/RouteFilterBar.test.tsx
Tested: npm run typecheck:web
Tested: npm run typecheck:web:test
Tested: npm run repo:drift-check
Not-tested: manual GitHub review in production browser after PR creation

* Keep route-detail motion PR lint-clean without changing behavior

CodeRabbit correctly flagged the new keyframes for using from/to selector
notation. This follow-up keeps the animation timing and properties the same
while switching to percentage selectors so the stylesheet aligns with the
configured keyframe selector rule.

Constraint: Keep the route-detail panel motion unchanged while satisfying the style rule mentioned in PR review
Rejected: Ignore the review comment | leaves a stylelint-style regression in the PR discussion unresolved
Confidence: high
Scope-risk: narrow
Reversibility: clean
Directive: When adding new keyframes in this stylesheet, prefer explicit percentage selectors to avoid repeating this lint issue
Tested: npm test -- src/web/pages/tokenRoutes.desktop-detail-panel.test.tsx src/web/pages/tokenRoutes.group-collapse.test.tsx src/web/pages/token-routes/RouteFilterBar.test.tsx
Tested: npm run typecheck:web
Tested: npm run repo:drift-check
Not-tested: remote Git transport from this machine still hangs, so branch update was handled separately from local git push

* Respect reduced-motion and narrow layer promotion for route detail panel

The new route detail panel motion path solved grid-driven jank, but the follow-up
review correctly flagged two polish issues: the animation should honor reduced
motion, and will-change should only stay enabled during active transitions. This
keeps the smoother motion path while reducing persistent layer cost and giving
reduced-motion users immediate state changes.

Constraint: Must preserve the non-layout animation path that fixed dropped frames in the route grid
Rejected: Restore anim-collapse behavior | reintroduces grid/layout-driven jank
Confidence: high
Scope-risk: narrow
Directive: Keep desktop route detail motion on transform and clip-path rather than grid height animation unless the panel moves out of the card grid
Tested: npm test -- src/web/pages/tokenRoutes.desktop-detail-panel.test.tsx src/web/pages/tokenRoutes.group-collapse.test.tsx src/web/pages/token-routes/RouteFilterBar.test.tsx
Tested: npm run typecheck:web
Tested: npm run typecheck:web:test
Tested: npm run repo:drift-check
Not-tested: Manual browser validation of prefers-reduced-motion on macOS

* Honor reduced-motion semantics in route detail panel lifecycle

The previous follow-up removed the always-on layer hint and added reduced-motion
CSS, but the enter state still reused the long-lived open class and the desktop
close path kept a fixed JS delay. This narrows will-change to a transient
entering state, bypasses close delays for reduced-motion users, and locks the
behavior with a regression test.

Constraint: Must preserve the non-layout detail-panel motion path that fixed grid jank
Rejected: Keep reduced-motion as CSS-only | JS close timer still delayed unmount and active-state cleanup
Rejected: Drop the close delay globally | would remove the intended close animation for standard-motion users
Confidence: high
Scope-risk: narrow
Directive: If the desktop detail panel motion changes again, keep motion-state CSS and JS timers aligned for prefers-reduced-motion users
Tested: npm test -- src/web/pages/tokenRoutes.desktop-detail-panel.test.tsx src/web/pages/tokenRoutes.group-collapse.test.tsx src/web/pages/token-routes/RouteFilterBar.test.tsx
Tested: npm run typecheck:web
Tested: npm run typecheck:web:test
Tested: npm run repo:drift-check
Not-tested: Manual browser verification of prefers-reduced-motion on macOS
 2026-04-10 11:01:24 +08:00
Cita c6a28c71c4 [codex] improve LobeHub brand detection coverage (#464) 
* Recognize more LobeHub-backed model brands so marketplace filters stop collapsing into other

Metapi was leaving many models under the uncategorized bucket even though the
current LobeHub icon set already contains matching provider or vendor brands.
This change moves brand detection into one shared registry, expands the rules
with the user-reported gaps that have real upstream icon coverage, and makes
server-side brand blocking reuse the same classification result as the web UI.

Constraint: Existing workspace has unrelated in-progress edits, so this commit stages only the brand-classification slice
Constraint: Brand matching must stay consistent between marketplace display and server-side blocked-brand filtering
Rejected: Add more ad hoc rules separately in web and server files | would keep the drift bug alive
Rejected: Blindly import every LobeHub slug as a model brand | would pollute filters with tool and app brands
Confidence: high
Scope-risk: moderate
Reversibility: clean
Directive: Keep new brand additions in src/server/shared/modelBrand.ts and let web/server consume that single source of truth
Tested: npm test -- src/web/components/BrandIcon.test.ts src/server/services/brandMatcher.test.ts src/web/pages/Models.marketplace-text.test.tsx src/web/components/BrandIcon.architecture.test.ts src/web/components/BrandIcon.render.test.tsx
Tested: npm run typecheck
Tested: npm run repo:drift-check
Not-tested: Live browser verification against the user's current marketplace dataset after deployment

* Preserve provider brand blocking without changing display-brand priority

The first pass unified brand detection but server-side blocked-brand checks
started relying on the single display brand. Mixed model paths such as
`deepinfra/meta-llama/...` and `azureai/gpt-4o` still need provider markers to
match global blocked brands even while the UI continues to show the preferred
vendor label.

Constraint: Marketplace display should keep the current preferred vendor-first brand label
Constraint: Server-side blocked-brand matching must still recognize provider and vendor markers on the same model id
Rejected: Reorder display-brand priority to make provider blocks pass | would regress the marketplace labels the PR was improving
Rejected: Reintroduce a separate server-only matcher | would recreate the web/server drift this PR removed
Confidence: high
Scope-risk: narrow
Reversibility: clean
Directive: Use getMatchingBrandNames for blocking-style checks and reserve getBrand for single-label display surfaces
Tested: npm test -- src/server/shared/modelBrand.test.ts src/server/services/brandMatcher.test.ts src/web/components/BrandIcon.test.ts src/web/pages/Models.marketplace-text.test.tsx src/web/components/BrandIcon.architecture.test.ts src/web/components/BrandIcon.render.test.tsx
Tested: npm run typecheck
Tested: npm run repo:drift-check
Not-tested: Live GitHub review-thread auto-resolution behavior after push

* Honor legacy blocked brand casing when canonicalizing global brand filters

The shared brand matcher now supports multi-match provider blocking, but the
blocked-brand rule parser still required exact display-case brand names. That
meant imported or legacy settings like `openai` or `aws bedrock` were silently
ignored even though they should map to known brands.

Constraint: Existing saved settings may contain lower-case or whitespace-variant brand names from imports or older data
Constraint: The server should keep emitting canonical display names after normalizing user-provided blocked brand entries
Rejected: Assume the settings UI always writes canonical brand strings | does not cover imported or hand-edited configuration
Rejected: Normalize only at the settings route | would still leave hydrated legacy config values ineffective in modelService
Confidence: high
Scope-risk: narrow
Reversibility: clean
Directive: Keep blocked-brand parsing tolerant of case and spacing drift, but always return canonical brand names for downstream use
Tested: npm test -- src/server/services/brandMatcher.test.ts src/server/shared/modelBrand.test.ts src/web/components/BrandIcon.test.ts src/web/pages/Models.marketplace-text.test.tsx src/web/components/BrandIcon.architecture.test.ts src/web/components/BrandIcon.render.test.tsx
Tested: npm run typecheck
Tested: npm run repo:drift-check
Not-tested: Manual settings UI round-trip with legacy lowercase globalBlockedBrands payloads
 2026-04-09 21:43:43 +08:00
Cita baead855dd Make admin reads snapshot-first for faster ops pages (#457) 
* Make admin reads snapshot-first so heavy pages stay responsive

This introduces a lightweight snapshot/cache layer for the busiest
admin reads, splits dashboard and proxy-log loading into smaller
independent surfaces, and moves accounts/site/dashboard snapshots
toward service-owned read paths.

The UI now loads dashboard summary, dashboard insights, site stats,
accounts, and proxy-log metadata as separate progressive reads while
keeping existing feature coverage intact.

Constraint: Must keep the full admin feature set and core metrics intact
Constraint: Interactive admin flows should trend toward <=3s without relying on OpenResty-only band-aids
Rejected: Delete heavy pages or reduce statistics depth | user explicitly requires unchanged functionality
Rejected: Keep one giant proxy-log/dashboard response | preserves current timeout-prone read shape
Confidence: medium
Scope-risk: moderate
Directive: Preserve old endpoints during the migration and keep new snapshot/query-v2 surfaces as the preferred frontend path
Tested: npm run typecheck
Tested: npx vitest run --root . src/server/routes/api/accounts.snapshot-v2.test.ts src/server/routes/api/stats.snapshot-v2.test.ts src/server/routes/api/stats.proxy-logs.test.ts src/server/routes/api/stats.siteStatus.test.ts src/server/routes/api/accounts.todayRewardFallback.test.ts
Tested: npm run build
Tested: npm run repo:drift-check
Not-tested: Live cita/cita1 latency measurements against the production dataset

* Keep snapshot services lean after the admin read-path rollout

The snapshot-first rollout now has fresh production evidence on cita1, so this follow-up trims two no-op patterns without changing behavior: a single-element Promise.all and a catch-then-rethrow refresh chain. Keeping the service layer lean reduces noise before final Ralph sign-off and redeploy verification.

Constraint: Keep deployed behavior unchanged while satisfying the mandatory deslop pass
Rejected: Wider refactor across route files | would broaden the verified surface right before production comparison closeout
Confidence: high
Scope-risk: narrow
Reversibility: clean
Directive: Keep snapshot services focused on cache/read orchestration; avoid reintroducing decorative async wrappers
Tested: npm run typecheck; npm run build; targeted vitest snapshot/proxy-log/account suites; npm run repo:drift-check
Not-tested: Public Cloudflare path, which still appears to hit a different origin than cita1

* Keep admin snapshots warm without introducing Redis

This moves the new admin read path beyond process-local caching by persisting
snapshot payloads in a dedicated admin_snapshots table and warming them in
the background. It also migrates remaining lightweight internal callers away
from the heaviest legacy reads and marks legacy endpoints as deprecated
instead of deleting them abruptly.

Constraint: User explicitly rejected adding Redis for admin snapshot acceleration
Rejected: Redis-backed shared cache | adds a forbidden runtime dependency
Rejected: Delete legacy endpoints immediately | still breaks tests, docs, and compatibility callers
Confidence: high
Scope-risk: moderate
Directive: Remove legacy admin endpoints only after internal callers, docs, and compatibility windows are cleared
Tested: npm run typecheck
Tested: npm run build
Tested: npx vitest run --root . src/server/services/adminSnapshotStore.test.ts src/server/routes/api/accounts.snapshot-v2.test.ts src/server/routes/api/stats.snapshot-v2.test.ts src/server/services/startupInfo.test.ts
Tested: npm run repo:drift-check
Not-tested: cita1 staging redeploy on this follow-up commit

* Collapse admin reads onto the canonical API paths

This removes the parallel v2 read surface and routes the snapshot-first
implementation back through the original admin API names. The frontend now
uses the canonical paths again while the backend keeps the newer snapshot,
persistence, and warm-refresh machinery behind those routes. Along the way it
also fixes the main review findings around cache coalescing, active-site scope,
atomic snapshot writes, and auth-header handling.

Constraint: User requested no Redis and no long-lived duplicate admin read endpoints
Rejected: Keep both legacy and v2 endpoints indefinitely | doubles maintenance and confuses the canonical contract
Rejected: Delete old names without remapping callers | would create avoidable frontend and tooling churn
Confidence: high
Scope-risk: moderate
Directive: Treat /api/stats/dashboard, /api/accounts, /api/stats/proxy-logs, and the site stats routes as the canonical admin read contract unless a future breaking-change plan says otherwise
Tested: npm run typecheck
Tested: npm run build
Tested: npx vitest run --root . src/server/services/adminSnapshotStore.test.ts src/server/routes/api/accounts.snapshot-v2.test.ts src/server/routes/api/stats.snapshot-v2.test.ts src/server/routes/api/stats.proxy-logs.test.ts src/server/services/startupInfo.test.ts
Tested: npm run repo:drift-check
Not-tested: cita1 staging redeploy on this canonical-route follow-up commit

* Keep canonical admin analytics fast without raw log scans

This lands the usage-aggregate path as the single implementation behind the canonical admin routes, adds the aggregate schema/migration artifacts, and reconnects dashboard/site stats warming to the new service so the PR no longer sits in a half-projector state.

It also updates the cache and aggregate tests to reflect the real runtime behavior and validates the current branch on cita1 staging, which showed the app-side snapshot path is fast while the remaining 1.5s staging slowness lives on the NodePort path rather than inside the aggregate queries themselves.

Constraint: Must preserve the canonical old-path admin API contract while moving reads onto aggregate-backed snapshots
Constraint: Must not add Redis or a parallel second analytics implementation
Rejected: Keep usageAggregationProjectorService as a separate path | would preserve duplicate ownership and keep type wiring split
Rejected: Judge staging performance only from NodePort timings | hid that pod-local snapshot reads were already fast
Confidence: medium
Scope-risk: moderate
Directive: If dashboard or insights feels slow again on staging, compare NodePort and pod-local timings before changing aggregate queries
Tested: npm run typecheck; npx vitest run --root . src/server/services/adminSnapshotStore.test.ts src/server/services/usageAggregationService.test.ts src/server/services/snapshotCacheService.test.ts src/server/routes/api/accounts.snapshot-v2.test.ts src/server/routes/api/stats.snapshot-v2.test.ts src/server/routes/api/stats.proxy-logs.test.ts src/server/services/startupInfo.test.ts; npm run build; npm run repo:drift-check; cita1 staging deploy plus canonical-route curl benchmarks
Not-tested: cita1 real ingress/OpenResty path; multi-replica projector concurrency

* Prevent admin aggregate drift under concurrent warmers

This follow-up hardens the snapshot-first admin analytics path by adding a persisted projector lease, exact 24-hour dashboard counting, and regression coverage for lease contention and time-window behavior.

The goal is to keep the canonical admin routes correct when multiple workers are alive and to avoid quietly overstating proxy24h by reading hour buckets as if they were an exact sliding window.

Constraint: Projector coordination must work through the existing checkpoint table without adding Redis or a second background system
Constraint: Schema artifacts must stay additive under the repo's generated bootstrap/upgrade pipeline
Rejected: Remove the left-prefix day/hour indexes in this slice | schema:contract rejects non-additive index removals, so that cleanup needs a broader migration strategy
Confidence: high
Scope-risk: moderate
Directive: Keep projector claims DB-backed; do not regress to process-local inFlight-only dedupe for aggregate writes
Tested: npm run typecheck; npx vitest run --root . src/server/services/usageAggregationService.test.ts src/server/routes/api/stats.snapshot-v2.test.ts; npm run build; npm run repo:drift-check
Not-tested: Multi-host live contention beyond synthetic lease test; resolving CodeRabbit index-nit without additive-schema support

* Keep CI aligned with canonical admin snapshots

The admin snapshot cutover left a mixed test surface: MySQL schema artifacts still
classified admin_snapshots.snapshot_key as JSON, canonical /api/accounts callers
were asserted as arrays, and a few proxy tests mocked routeRefreshWorkflow too
narrowly, which leaked missing exports into later OAuth runs.

This commit narrows the schema metadata heuristic, updates the checked-in schema
artifacts and their regression tests, adds lightweight web test compat helpers
for canonical snapshot APIs, and preserves actual routeRefreshWorkflow exports so
full-suite workers no longer poison unrelated tests. OAuth/account token suites
also reset DATA_DIR-backed modules safely to avoid stale singleton config.

Constraint: checked-in schema artifacts drive cross-dialect CI parity checks
Constraint: vitest module mocks can leak across files in the same worker when exports are omitted
Rejected: rerun schema:generate only | additive guard rejects the logical-type correction for snapshot_key
Rejected: keep per-test ad hoc snapshot mocks | repeated breakage across pages needed one compat helper
Confidence: high
Scope-risk: moderate
Directive: when a test uses vi.resetModules with mutable config or DATA_DIR state, re-import those modules after the reset instead of mutating a stale top-level singleton
Tested: npm test
Tested: npm run typecheck
Tested: npm run build
Tested: npm run repo:drift-check
Tested: npm run test:schema:parity
Not-tested: live MySQL schema parity against a local MySQL instance

* Keep CodeQL from re-flagging already-limited routes

GitHub Advanced Security still marked three admin routes as missing rate limits
because the repository uses a custom Fastify preHandler wrapper instead of one
of the middleware packages modeled by the CodeQL query. The routes are already
throttled in production, so this change adds narrow in-source suppressions on the
three affected handlers to record that the check is a false positive instead of a
real missing guard.

Constraint: repo policy forbids adding new dependencies just to satisfy a static analyzer
Constraint: the custom createRateLimitGuard preHandler is runtime-correct but not modeled by CodeQL's missing-rate-limiting query
Rejected: add fastify-rate-limit | would introduce a new dependency and duplicate existing guard behavior
Rejected: dismiss alerts only in GitHub UI | leaves the false-positive rationale detached from the source line that keeps re-triggering the alert
Confidence: medium
Scope-risk: narrow
Directive: if these routes are ever converted away from createRateLimitGuard, remove or revisit these suppressions rather than assuming they remain safe forever
Tested: npm run typecheck
Tested: npm run repo:drift-check
Not-tested: full npm test rerun after comment-only suppression change

* Use legacy CodeQL suppression syntax for custom rate guards

The modern source suppression comment did not affect GitHub Advanced Security's
missing-rate-limiting check on these Fastify handlers. Switch the three known
false-positive locations to the legacy LGTM suppression syntax, keeping the
custom preHandler throttling in place while matching the syntax that CodeQL
still honors for in-source suppressions.

Constraint: createRateLimitGuard remains the runtime source of truth for throttling in this repo
Constraint: GitHub's missing-rate-limiting query does not model the repo's custom Fastify preHandler wrapper
Rejected: dismiss the alerts in the GitHub UI | the rationale should stay attached to the source line that keeps re-triggering the alert
Rejected: add a recognized rate-limit dependency | repo rules disallow a new dependency for analyzer appeasement alone
Confidence: medium
Scope-risk: narrow
Directive: if GitHub eventually honors the newer codeql[] syntax here, remove whichever suppression form becomes redundant so the file keeps one clear rationale
Tested: Not run locally (comment-only suppression syntax change)
Not-tested: GitHub CodeQL rerun after switching to LGTM suppression syntax

* Keep admin routes clean after CodeQL false-positive triage

The repository's custom createRateLimitGuard preHandlers are the actual runtime
throttles for these routes. Since GitHub Advanced Security still did not honor
the attempted in-source suppressions, remove the temporary comments and keep the
source focused on runtime behavior while the false-positive alerts are tracked
operationally in GitHub.

Constraint: the custom Fastify preHandler remains the only real throttling mechanism in this repo
Rejected: leave non-functional suppression comments in source | they imply enforcement that GitHub did not actually honor
Confidence: high
Scope-risk: narrow
Directive: if CodeQL adds custom Fastify preHandler modeling later, prefer removing any alert dismissals over reintroducing comment noise here
Tested: Not run locally (comment-only cleanup)
Not-tested: GitHub checks after alert dismissal
 2026-04-09 21:31:13 +08:00
cita-777 6cca74b039 Recognize more LobeHub-backed model brands so marketplace filters stop collapsing into other 
Metapi was leaving many models under the uncategorized bucket even though the
current LobeHub icon set already contains matching provider or vendor brands.
This change moves brand detection into one shared registry, expands the rules
with the user-reported gaps that have real upstream icon coverage, and makes
server-side brand blocking reuse the same classification result as the web UI.

Constraint: Existing workspace has unrelated in-progress edits, so this commit stages only the brand-classification slice
Constraint: Brand matching must stay consistent between marketplace display and server-side blocked-brand filtering
Rejected: Add more ad hoc rules separately in web and server files | would keep the drift bug alive
Rejected: Blindly import every LobeHub slug as a model brand | would pollute filters with tool and app brands
Confidence: high
Scope-risk: moderate
Reversibility: clean
Directive: Keep new brand additions in src/server/shared/modelBrand.ts and let web/server consume that single source of truth
Tested: npm test -- src/web/components/BrandIcon.test.ts src/server/services/brandMatcher.test.ts src/web/pages/Models.marketplace-text.test.tsx src/web/components/BrandIcon.architecture.test.ts src/web/components/BrandIcon.render.test.tsx
Tested: npm run typecheck
Tested: npm run repo:drift-check
Not-tested: Live browser verification against the user's current marketplace dataset after deployment
 2026-04-09 19:43:47 +08:00
cita-777 a3886324ca Merge remote-tracking branch 'origin/main' 2026-04-09 19:18:39 +08:00
cita-777 7d883a6ada update readme 2026-04-09 19:17:01 +08:00
dependabot[bot] 5e27684a1c chore(deps): bump the minor-and-patch group across 1 directory with 6 updates (#451) 
---
updated-dependencies:
- dependency-name: "@visactor/react-vchart"
  dependency-version: 2.0.21
  dependency-type: direct:production
  update-type: version-update:semver-patch
  dependency-group: minor-and-patch
- dependency-name: dotenv
  dependency-version: 17.4.1
  dependency-type: direct:production
  update-type: version-update:semver-minor
  dependency-group: minor-and-patch
- dependency-name: minimatch
  dependency-version: 10.2.5
  dependency-type: direct:production
  update-type: version-update:semver-patch
  dependency-group: minor-and-patch
- dependency-name: electron
  dependency-version: 41.1.1
  dependency-type: direct:development
  update-type: version-update:semver-patch
  dependency-group: minor-and-patch
- dependency-name: jsdom
  dependency-version: 29.0.2
  dependency-type: direct:development
  update-type: version-update:semver-patch
  dependency-group: minor-and-patch
- dependency-name: mermaid
  dependency-version: 11.14.0
  dependency-type: direct:development
  update-type: version-update:semver-minor
  dependency-group: minor-and-patch
...

Signed-off-by: dependabot[bot] <support@github.com>
Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com>
 2026-04-09 11:16:28 +08:00
Cita 03bebae17f fix oauth route unit delete rollback (#450) 2026-04-09 11:15:57 +08:00
puyujian 569a15e14c feat: enhance API key management and fix routing logic 
* ```
feat(accounts): 支持批量添加API密钥连接

- 添加accessTokens字段到账户创建载荷模式，允许传递多个API密钥
- 实现批量API密钥解析功能，支持换行符、空格和逗号分隔
- 重构账户创建逻辑以支持单个和批量API密钥处理
- 在前端界面中添加批量API密钥输入检测和处理
- 添加批量创建结果返回和错误处理
- 更新验证流程以支持批量模式下的逐条验证
- 添加详细的批量API密钥测试用例

该更改允许用户一次提交多个API密钥，系统将为每个密钥创建独立的连接并参与负载均衡。
```

* ```
fix(tokenRouter): 调整路由匹配优先级以优先匹配显示名称别名

当精确路由和显式组显示名称冲突时，现在优先选择显式组显示名称
而不是精确路由模式。这修正了路由决策逻辑，使显式组路由能够正
确覆盖精确模型匹配。

相关的测试用例已更新以反映新的匹配行为，确保显式组路由在冲
突情况下获得更高优先级。
```

* ```
fix(accounts): 修复API密钥验证错误消息显示逻辑

当凭证模式不为apikey时显示会话令牌提示信息，否则显示API密钥验证失败信息

feat(accounts): 更新API密钥输入界面提示文本

将批量添加说明从输入框占位符移至独立提示文本，
使界面更清晰易懂
```

* ```
feat(workflow): 在CI/CD工作流中使用动态Docker Hub镜像名称

- 在ci.yml和release.yml工作流中添加DOCKERHUB_IMAGE环境变量
- 将硬编码的Docker Hub用户名替换为从secrets.DOCKERHUB_USERNAME动态获取
- 更新docker.metadata-action配置以使用环境变量中的镜像名称
- 添加测试用例验证Docker Hub镜像名称的正确配置
```

* fix(accounts): 修复批量创建回归并下沉创建流程
 2026-04-07 14:28:25 +08:00
dependabot[bot] 5cab6c83f1 chore(deps-dev): bump react-router-dom from 7.13.2 to 7.14.0 
Bumps the routing group with 1 update: [react-router-dom](https://github.com/remix-run/react-router/tree/HEAD/packages/react-router-dom).


Updates `react-router-dom` from 7.13.2 to 7.14.0
- [Release notes](https://github.com/remix-run/react-router/releases)
- [Changelog](https://github.com/remix-run/react-router/blob/main/packages/react-router-dom/CHANGELOG.md)
- [Commits](https://github.com/remix-run/react-router/commits/react-router-dom@7.14.0/packages/react-router-dom)

---
updated-dependencies:
- dependency-name: react-router-dom
  dependency-version: 7.14.0
  dependency-type: direct:development
  update-type: version-update:semver-minor
  dependency-group: routing
...

Signed-off-by: dependabot[bot] <support@github.com>
Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com>
 2026-04-07 14:28:13 +08:00
dependabot[bot] 2f2ebcb37c chore(deps-dev): bump @types/nodemailer from 7.0.11 to 8.0.0 
Bumps [@types/nodemailer](https://github.com/DefinitelyTyped/DefinitelyTyped/tree/HEAD/types/nodemailer) from 7.0.11 to 8.0.0.
- [Release notes](https://github.com/DefinitelyTyped/DefinitelyTyped/releases)
- [Commits](https://github.com/DefinitelyTyped/DefinitelyTyped/commits/HEAD/types/nodemailer)

---
updated-dependencies:
- dependency-name: "@types/nodemailer"
  dependency-version: 8.0.0
  dependency-type: direct:development
  update-type: version-update:semver-major
...

Signed-off-by: dependabot[bot] <support@github.com>
Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com>
 2026-04-07 14:28:04 +08:00
cita-777 63c435c901 fix update center release tests for 1.3.0 2026-04-06 15:45:58 +08:00
cita-777 f18aa98888 fix desktop release packaging rebuild 2026-04-06 15:37:22 +08:00
cita-777 566501be1f bump version to 1.3.0 2026-04-06 15:19:18 +08:00
Cita 42f9049aff [codex] align antigravity special-model non-stream path with CPA (#444) 
* align antigravity special-model non-stream path with cpa

* fix antigravity tail aggregation review feedback

* fix antigravity fallback aggregation review feedback
 2026-04-06 15:03:55 +08:00
Cita 448f488f95 [codex] improve oauth route unit feedback (#445) 
* feat: improve oauth route unit feedback

* fix: harden oauth route unit feedback flow
 2026-04-06 15:03:33 +08:00
Cita d1b42b2236 fix: support oauth route unit inserts on postgres (#443) 
* fix proxy debug undici response header capture

* fix: support oauth route unit inserts on postgres
 2026-04-06 13:39:05 +08:00
Cita 2b9200ea7c fix proxy debug undici response header capture (#442) 2026-04-06 13:16:46 +08:00
Cita 2f0e63a1e0 [codex] add oauth route pools and proxy save flow (#440) 
* feat: add oauth route pools and proxy save flow

* fix: align oauth route pool schema and rate limits

* fix: harden oauth route pool review fixes

* fix: address oauth ci regressions

* fix: close oauth codeql alerts

* fix: harden oauth route unit recovery

* fix: split oauth route limiters for codeql

* fix: address remaining oauth review comments
 2026-04-06 11:55:20 +08:00
Cita a789ddf7f8 [codex] add sub2api managed refresh resilience (#441) 
* add sub2api managed refresh resilience

* serialize sub2api managed refresh per account

* bound sub2api refresh scheduler work

* tighten sub2api refresh scheduler rules
 2026-04-06 11:43:30 +08:00
Cita 3edeb6e245 feat: refine OAuth proxy controls and quota UI (#433) 
* feat: refine oauth management proxy controls

* fix: preserve oauth refresh state and tighten oauth rate limiting

* fix: satisfy codeql oauth rate limiting

* fix: address oauth review comments

* fix: move oauth sensitive limits into prehandlers

* fix: cap oauth quota refresh batch size
 2026-04-06 08:50:19 +08:00
Cita 287c5aafd6 fix: localize downstream key trend timestamps (#432) 
* fix: localize downstream key trend timestamps

* fix: keep downstream trend metadata on empty responses

* fix: cursor paginate downstream key trend reads

* fix: normalize empty downstream trend timezones

* fix: localize windowed downstream trend buckets
 2026-04-06 08:46:40 +08:00
Cita 3e8d69bed6 fix codex compact non-stream accept header (#439) 2026-04-06 08:46:27 +08:00
Cita 38721cb890 [codex] support downstream key site and credential exclusions (#431) 
* support downstream key site and credential exclusions

* skip electron binary download in non-desktop ci

* fix migrate partial-journal test for 0020
 2026-04-05 23:43:07 +08:00
Cita 492f43c5dc [codex] add oauth pre-refresh resilience (#430) 
* oauth pre-refresh resilience

* address oauth refresh review comments
 2026-04-05 22:58:50 +08:00
Cita 6feda0e7ba [codex] fix downstream client detection boundaries (#429) 
* fix downstream client detection boundaries

* address downstream client detection review comments
 2026-04-05 22:38:00 +08:00
Cita 193f3e7181 [codex] fix proxy log usage source metadata (#428) 
* fix proxy log usage source metadata

* fix ci follow-up comment regressions
 2026-04-05 21:57:08 +08:00
Cita c10b1e7bca [codex] polish settings transport and probe cards (#427) 
* polish settings transport and probe cards

* restore compact responses fallback control
 2026-04-05 21:47:49 +08:00
Cita d5560fb036 [codex] normalize primary site URL handling (#424) 
* normalize primary site url handling

* fix site create redirect test selector

* fix sub2api gemini model discovery and site detect race

* fix sub2api antigravity fallback and test selectors

* fix site modal wording test

* guard blur detect against manual platform changes
 2026-04-05 20:09:34 +08:00
Cita df75a80bf9 Fix responses compact fallback handling (#426) 
* fix route drag overlay alignment

* fix(web): address route drag review comments

* fix route card review follow-up

* Fix responses compact fallback handling

* Fix compact endpoint candidate typing

* Tighten compact fallback matcher
 2026-04-05 19:41:09 +08:00
Cita b3f6fa0d4f [codex] align site created modal with shared actions (#425) 
* align site created modal with shared actions

* address site created modal review comments
 2026-04-05 19:34:10 +08:00
Cita ef1962d10b [codex] rename site API request wording (#423) 
* rename site api request wording

* replace real site example domains
 2026-04-05 19:16:08 +08:00
Cita 5b005d8412 fix: tighten generic upstream passthrough headers (#422) 
* fix: tighten generic upstream passthrough headers

* fix: preserve codex passthrough version headers
 2026-04-05 18:11:42 +08:00
Cita afbbc4c79a fix failed expired api-key recovery route preservation (#421) 2026-04-05 17:41:35 +08:00
Cita 9045a488f0 [codex] Fix desktop default-browser external links (#420) 
* fix desktop default-browser external links

* fix desktop navigation guard review follow-up
 2026-04-05 17:40:54 +08:00
Cita ff43fce9a7 [codex] fix route drag overlay alignment (#419) 
* fix route drag overlay alignment

* fix(web): address route drag review comments

* fix route card review follow-up
 2026-04-05 17:33:53 +08:00
Cita b3e987a2f5 [daily] keep codex continuation current across scope roundtrips (#416) 2026-04-05 17:29:42 +08:00
Cita 63f6b07842 [daily] cap sqlite migration recovery retries (#410) 
* [daily] cap sqlite migration recovery retries

* fix typecheck for sqlite retry budget guard
 2026-04-03 11:10:55 +08:00
Cita bc3893ff3b [codex] refine token routes workspace motion and hierarchy (#394) 
* refine token routes workspace motion and hierarchy

* address route workspace review feedback

* Refine token route density and motion

* [codex] refine token routes motion behavior

* [codex] address route motion review comments

* [codex] tighten route row interaction states
 2026-04-03 11:04:40 +08:00
Cita af5b62fd8b [codex] fix codex responses continuation across channel drift (#404) 
* fix codex responses continuation across channel drift

* fix: clear codex responses continuation fallback on scoped reset

* fix: harden codex continuation store keying
 2026-04-03 11:00:53 +08:00
Cita b9b553d772 [codex] fix sqlite migration journal recovery (#400) 
* fix sqlite migration journal recovery

* address sqlite migration review follow-ups
 2026-04-02 17:28:45 +08:00
Cita 6ad9ec6911 [codex] strip codex responses max_output_tokens (#399) 
* strip codex responses max_output_tokens

* address codex responses review comments
 2026-04-02 17:28:38 +08:00
Cita 19bfed2e33 [codex] refresh integration and settings docs for current UI and provider coverage (#398) 
* docs: refresh integration and settings guides

* docs: address review follow-up
 2026-04-02 17:28:27 +08:00
Cita 2be0603e6f [codex] fix expired connection health recovery (#393) 
* fix expired connection health recovery

* address review comments and test regressions
 2026-04-02 17:27:42 +08:00
Cita 082891a217 [codex] fix runtime settings restart hydration (#392) 
* fix runtime settings restart hydration

* fix review followups for settings hydration

* dedupe log cleanup day normalization
 2026-04-02 17:27:25 +08:00
Cita 1407f754b1 [codex] add Fedora desktop rpm packaging (#390) 
* add Fedora desktop rpm packaging

* harden desktop packaging yaml assertion
 2026-04-02 12:53:28 +08:00
Cita ed2783e2dd [codex] fix route detail dropdown clipping (#388) 
* fix route detail dropdown clipping

* test: refresh proxy route mocks for ci
 2026-04-02 11:19:07 +08:00
Cita 52c6ff5e5c [daily] route codex websocket through site api endpoints (#386) 
* fix: route codex websocket through site api endpoints

* fix: preserve websocket endpoint exhaustion errors

* test: align proxy route mocks with first-byte timeout helpers
 2026-04-02 11:18:30 +08:00
Cita 180d17adfc feat: add proxy first-byte timeout and log badges (#383) 
* add proxy first-byte timeout and log badges

* fix first-byte timeout review feedback
 2026-04-02 10:00:11 +08:00
Cita bcd758edac test: harden background task completion waits (#382) 2026-04-02 09:49:50 +08:00
Cita ace5ddd52b fix edit payload clearing boundaries (#381) 2026-04-02 09:49:39 +08:00
Cita 4ca88d0fe5 [codex] fix responses-to-chat tool stream fidelity (#378) 
* fix responses chat tool stream fidelity

* fix responses tool call follow-up review comments
 2026-04-02 09:49:23 +08:00
Bainily 596d1b93cb feat(server): add proactive channel probes and load-aware stable routing / 服务端新增主动探活与负载感知稳定路由 (#330) 
* wip: preserve local changes before upstream merge

* Improve proxy routing stability and add stable-first strategy

* Sync explicit-group routing strategy to eligible source routes

* Fix proxy retry and runtime health review issues

* fix: make proxy channel retry attempts configurable

* fix: harden proxy retry recovery and bookkeeping

* fix: address pr 257 review comments

* feat(proxy): add sticky session channel coordination

* feat(server): add proactive channel probes and load-aware stable routing

* test(server): stabilize session load routing selection assertion

* fix(proxy): harden codex forwarding stability

* fix(router): rotate stable-first channels by healthy order

* fix(server): address probe review feedback

* fix(server): address probe review follow-ups

* fix(ci): address CodeQL and core test failures

* feat(server): refine stable-first routing recovery and observation

* Finish PR 330 settings and review fixes

* Fix chat site endpoint CI mock

* Address latest PR 330 review comments

---------

Co-authored-by: Cita <juricek.chen@gmail.com>
 2026-04-02 09:49:04 +08:00
Cita 1133846998 [codex] restore route priority drag behavior (#376) 
* fix: restore route priority drag behavior

* fix: use theme rail highlight surface
 2026-04-01 21:24:25 +08:00
Cita 5fffcb6d66 feat: support CIDR admin allowlists (#377) 2026-04-01 21:06:13 +08:00
Cita 76c85d0a13 [codex] Split site API endpoint pool from panel host (#373) 
* feat: add site api endpoint schema scaffolding

* feat: wire site api endpoints into backup migration

* feat: add site api endpoint selection service

* feat: add site api endpoint contracts

* feat: route discovery through site api endpoints

* feat: route proxy traffic through site api endpoints

* feat: add site api endpoint pool editor

* fix: keep proxy video tasks on site endpoint pool

* fix: restore core test compatibility for site endpoint pool

* fix: address endpoint pool review findings
 2026-04-01 20:58:37 +08:00
Cita ce77bde95a fix: align route priority drag preview (#375) 2026-04-01 19:43:00 +08:00
Cita 37a86d1380 [codex] background route decision refresh (#370) 
* background route decision refresh

* address route decision refresh review

* fix route decision refresh typing
 2026-04-01 18:24:14 +08:00
Cita 6e21f911ea [codex] add route priority left rail (#371) 
* feat: add route priority left rail

* fix: drop stale route card test prop
 2026-04-01 18:12:42 +08:00
Cita 21d92e1887 fix: recognize structured oauth accounts in routing (#369) 
* fix: recognize structured oauth accounts in routing

* fix: use structured oauth accounts in account list
 2026-04-01 17:15:22 +08:00
Cita e2d9481b95 fix anyrouter balance refresh challenge errors (#368) 2026-04-01 16:53:01 +08:00
Cita 532be86e93 [codex] Add route cooldown controls (#365) 
* Add route cooldown controls

* Address route cooldown review comments
 2026-04-01 16:41:25 +08:00
Cita 1e0dffe543 [codex] Fix mysql insert boundary handling (#364) 
* fix mysql insert boundary handling

* fix review comment follow-ups

* fix account insert boundary regressions
 2026-04-01 14:33:45 +08:00
Cita aac1307470 [codex] add vendor code entry presets follow-up (#363) 
* address coding plan review comments

* add more vendor code entry presets
 2026-04-01 13:57:24 +08:00
Cita 3ebe851002 Fix update helper health for ready failed release (#361) 2026-04-01 12:56:42 +08:00
Cita bafceb855b [codex] Add model tester fixed-channel selection (#352) 
* feat: add model tester forced channel

* fix: keep codex websocket defaults and route refresh checks

* fix: scope tester-only forced channel overrides

* fix: keep tester hydration and websocket hints internal

* fix: reject gemini on legacy tester chat routes

* fix: harden forced channel selection edges
 2026-04-01 12:56:13 +08:00
Cita 8c3be1a613 Add zod payload contracts for admin API routes (#358) 
* Add zod route payload contracts for admin APIs

* Fix review follow-ups for zod admin payloads

* Refactor account payload parser helpers
 2026-04-01 12:52:55 +08:00
nodca 6a55effd3b 修复 weighted 路由失败退避时间溢出导致服务崩溃 (#354) 
* fix: cap token router cooldown backoff

* docs: explain token router cooldown cap
 2026-04-01 12:29:05 +08:00
Cita 4096c757d4 [codex] fix anyrouter checkin session failure classification (#353) 
* fix anyrouter checkin session failure classification

* fix auth failure classification review follow-up
 2026-04-01 12:28:09 +08:00
Cita 6206c5bd77 fix(web): preserve both site-created next steps (#357) 2026-04-01 09:47:21 +08:00
Cita 0de9c5e3f1 [codex] add coding plan site initialization flow (#351) 
* add coding plan site initialization flow

* fix ci for coding plan site init flow

* address coding plan review comments
 2026-03-31 21:55:25 +08:00
Cita e74e11375c [codex] add route priority bucket editor (#350) 
* feat: add route priority bucket editor

* fix: address route editor review comments
 2026-03-31 21:23:02 +08:00
Cita baa11d7787 cache update center status snapshots (#349) 2026-03-31 20:47:02 +08:00
Cita d930b87762 [codex] Fix Anyrouter model sync shield handling (#348) 
* fix anyrouter model sync shield handling

* fix shield challenge message precedence
 2026-03-31 19:32:25 +08:00
Cita 87390651f4 fix: add searchable token account selectors (#347) 2026-03-31 19:13:07 +08:00
Cita 6b19d06140 [codex] fix empty stream success handling and unknown usage logs (#343) 
* fix: preserve repeated short responses deltas

* fix empty stream success handling and unknown usage logs

* fix proxy usage metadata typing

* fix stream bookkeeping and explicit zero usage source

* fix sticky fast path and usage placeholder detection
 2026-03-31 16:45:13 +08:00
Cita 3ce5179fed fix: detect latest digest updates in update center (#344) 2026-03-31 15:02:24 +08:00
rcocco e8921e63ce Fix orphaned responses tool outputs in messages fallback (#342) 2026-03-31 14:56:54 +08:00
Cita 6e04db61dd fix: wire site-created dialog cancel cleanup (#341) 2026-03-31 13:47:36 +08:00
Cita 618ca0b9bf fix: restore armv7 docker base image (#337) 2026-03-30 23:23:55 +08:00
Cita eb65a2be88 fix: preserve repeated short responses deltas (#336) 2026-03-30 22:54:05 +08:00
Cita 5d54e92dc6 docs: add management API guide (#334) 2026-03-30 22:53:33 +08:00
Cita 9e95819952 fix: decode zstd-compressed SSE proxy surfaces (#335) 
* Fix zstd-compressed SSE decoding in proxy surfaces

* Fix stream/web type bridge for zstd SSE

* Guard zstd stream readers against decoded bodies

* Handle stacked zstd stream encodings
 2026-03-30 22:46:31 +08:00
Cita 9eb33df6d4 [codex] add automatic update-center reminders (#333) 
* add automatic update-center reminders

* fix update-center reminder review issues
 2026-03-30 22:37:24 +08:00
Cita 26f9717ad7 [codex] add setting to disable cross-protocol fallback (#332) 
* Add toggle to disable cross-protocol fallback

* Tighten runtime settings payload typing
 2026-03-30 20:02:51 +08:00
Cita 6726da987f persist proxy trace panel state (#331) 2026-03-30 19:21:57 +08:00
Cita 9aeec87cfa chore: sweep dependabot updates and align Node 25 (#329) 
* chore: sweep dependabot updates

* fix: narrow optional browser Buffer typing

* chore: align repo node pins to v25
 2026-03-30 19:14:41 +08:00
Delicious233 9212b765cd feat: 新站点创建后显示选择对话框 (#302) 
* feat: 实现全局模型白名单功能

## 功能概述
实现全局模型白名单，允许管理员配置只启用特定模型的路由，实现精细化的模型访问控制。

## 主要变更

### 后端实现
- config.ts: 新增 globalAllowedModels 配置项
- settings.ts:
  - 新增 RuntimeSettingsBody 类型支持
  - 实现数据库加载和持久化
  - 配置变更自动触发路由重建
- modelService.ts:
  - 在路由重建中添加白名单过滤逻辑
  - 大小写不敏感匹配，自动trim空格
  - 空白名单时允许所有模型（向后兼容）
- stats.ts:
  - 候选API过滤 models/modelsWithoutToken/modelsMissingTokenGroups

### 前端实现
- Settings.tsx:
  - 新增"全局模型白名单"配置卡片
  - 支持手动输入和点击选择两种添加方式
  - 绿色徽章显示已选模型，支持删除
  - 保存后自动触发路由重建

## 技术特性
- ✅ 向后兼容（默认为空数组，允许所有模型）
- ✅ 大小写不敏感匹配
- ✅ 自动trim和去重
- ✅ 输入验证（类型检查、空值过滤）
- ✅ 配置变更自动重建路由

## 测试验证
- 白名单为空时所有模型可见
- 白名单有值时只显示白名单模型
- 路由重建正确过滤模型
- 候选API正确返回过滤结果
- 前端UI交互正常

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

* feat: 站点创建后显示选择对话框

新站点创建后不再根据平台类型自动跳转，而是显示一个选择对话框让用户决定下一步操作：
- 添加账号（用户名密码登录）
- 添加 API Key
- 稍后配置

对于 codex 平台，选择"添加账号"时会跳转到 OAuth 流程，其他平台则跳转到账号管理页面。

这样可以避免用户被强制跳转，提供更灵活的配置选择。

* fix: add getModelTokenCandidates mock to Settings tests

* fix: add getModelTokenCandidates mock to proxy-transport test

---------

Co-authored-by: Ding <ding@local>
Co-authored-by: Claude Sonnet 4.6 <noreply@anthropic.com>
 2026-03-30 18:51:23 +08:00
Delicious233 fa25a501a8 feat: 实现全局模型白名单功能 (#301) 
* feat: 实现全局模型白名单功能

## 功能概述
实现全局模型白名单，允许管理员配置只启用特定模型的路由，实现精细化的模型访问控制。

## 主要变更

### 后端实现
- config.ts: 新增 globalAllowedModels 配置项
- settings.ts:
  - 新增 RuntimeSettingsBody 类型支持
  - 实现数据库加载和持久化
  - 配置变更自动触发路由重建
- modelService.ts:
  - 在路由重建中添加白名单过滤逻辑
  - 大小写不敏感匹配，自动trim空格
  - 空白名单时允许所有模型（向后兼容）
- stats.ts:
  - 候选API过滤 models/modelsWithoutToken/modelsMissingTokenGroups

### 前端实现
- Settings.tsx:
  - 新增"全局模型白名单"配置卡片
  - 支持手动输入和点击选择两种添加方式
  - 绿色徽章显示已选模型，支持删除
  - 保存后自动触发路由重建

## 技术特性
- ✅ 向后兼容（默认为空数组，允许所有模型）
- ✅ 大小写不敏感匹配
- ✅ 自动trim和去重
- ✅ 输入验证（类型检查、空值过滤）
- ✅ 配置变更自动重建路由

## 测试验证
- 白名单为空时所有模型可见
- 白名单有值时只显示白名单模型
- 路由重建正确过滤模型
- 候选API正确返回过滤结果
- 前端UI交互正常

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

* fix: add getModelTokenCandidates mock to Settings tests

* fix: add getModelTokenCandidates mock to proxy-transport test

---------

Co-authored-by: Ding <ding@local>
Co-authored-by: Claude Sonnet 4.6 <noreply@anthropic.com>
 2026-03-30 17:19:02 +08:00
Cita 01481be511 [codex] Add digest-safe k3s update-center assets (#326) 
* Add digest-safe k3s update-center assets

* Harden k3s update-center assets

* Trim k3s env secret names safely
 2026-03-30 17:17:24 +08:00
Cita 7d91823f6c Add site filters for manual connection selection (#328) 2026-03-30 16:32:48 +08:00
Cita 0d2c4501c2 make proxy trace panel collapsible (#327) 2026-03-30 16:32:26 +08:00
Cita 26d87db2cb [codex] tighten update center and proxy debug UX (#325) 
* tighten update center and proxy debug UX

* Address update center review feedback
 2026-03-30 13:39:20 +08:00
Cita 71be4cb63a Handle codex OAuth usage-limit cooldowns (#316) 
* Handle codex oauth usage-limit cooldowns

* Generalize short-window 429 limit cooldowns

* Fan out short-window cooldowns by credential
 2026-03-30 13:39:07 +08:00
Cita d47c3c4a29 Support digest-aware update center rollbacks (#318) 2026-03-29 22:16:39 +08:00
Cita b9ae85e98b Fix update center helper token lookup (#317) 2026-03-29 19:49:13 +08:00
cita-777 faf9874779 Fix armv7 docker helper build 2026-03-29 17:57:41 +08:00
Cita 11583c51b9 [codex] add K3s update center (#314) 
* add k3s update center

* fix update center status timeouts

* Polish update center settings UI

* Document k3s update center

* Refocus update center docs for users

* Clarify k3s migration path in docs
 2026-03-29 17:43:49 +08:00
Cita dcfd45ea65 Fix proxy debug trace truncation previews (#313) 2026-03-29 15:08:37 +08:00
Cita 7092e2f129 [codex] refine proxy logs debug UI follow-ups (#312) 
* Refine proxy logs debug page layout

* Align proxy logs debug UI with page patterns

* Prevent proxy trace detail refresh flicker

* Polish proxy trace detail modal
 2026-03-29 13:39:25 +08:00
Cita ab8640c8c3 [daily] reset oauth proxy form after start (#311) 2026-03-29 13:37:40 +08:00
Cita ed44e7f925 Refine proxy logs debug trace UI (#309) 2026-03-29 11:50:16 +08:00
Cita 03ca1154a0 Add OAuth account proxy controls (#307) 
* Add oauth account proxy controls

* Refine oauth proxy review fixes

* Fix oauth clear-proxy exchange fallback
 2026-03-29 00:35:45 +08:00
Cita 785ee93505 fix gemini oauth validation site proxy (#298) 2026-03-28 20:06:20 +08:00
Cita 4d4684a39b [codex] add proxy debug tracing (#299) 
* add proxy debug tracing

* fix proxy debug response header typing

* extend proxy debug tracing to side paths

* Refine proxy debug trace review fixes

* Stabilize proxy debug attempt indexing

* Tighten proxy debug trace accuracy
 2026-03-28 20:05:48 +08:00
Sean Lee 3bf3cd1622 feat: 新增路由批量禁用/启用功能 (#295) 
* feat: Preserve manual models during discovery and refresh, and add Claude configuration files and project documentation.feat: Preserve manual models during discovery and refresh, and add Claude configuration and project documentation files.

* fix: fix Feishu and Larksuite webhook support to the notification service with updated UI and tests.

* feat: 新增路由批量禁用/启用功能

- 后端新增 POST /api/routes/batch 接口，支持批量 enable/disable
- 前端新增批量操作模式，支持 checkbox 选择路由
- 浮动操作栏显示选中数量，支持全选/取消全选
- 批量操作完成后自动退出选择模式并刷新列表

* fix: complete route batch actions on mobile

---------

Co-authored-by: Xiang Li <xiangli>
Co-authored-by: cita-777 <juricek.chen@gmail.com>
 2026-03-28 16:54:09 +08:00
Cita 5ae452ab45 [codex] inherit site proxy settings for oauth (#296) 
* test: define oauth proxy inheritance behavior

* feat: apply site proxy settings to oauth requests

* feat: backfill oauth provider sites at startup

* test: remove oauth site registry temp dir
 2026-03-28 16:38:39 +08:00
apple 40b8eddef8 chore: remove committed local debug artifacts 2026-03-26 21:59:48 +08:00
Cita 8ebfc39745 [codex] add harness engineering guardrails (#284) 
* refactor: add harness engineering guardrails

* fix: address harness review feedback

---------

Co-authored-by: apple <apple@appledeMacBook-Pro.local>
 2026-03-26 21:22:36 +08:00
Cita b3387dfba7 [codex] fix cross-database JSON boundary handling (#283) 
* fix: normalize cross-database json boundaries

* fix: address json boundary review comments

---------

Co-authored-by: apple <apple@appledeMacBook-Pro.local>
 2026-03-26 20:21:19 +08:00
Cita 7e1fb8eb1b [codex] HTTP-first Codex upstream websocket settings (#280) 
* http-first codex upstream websocket settings

* address websocket runtime review comments

---------

Co-authored-by: apple <apple@appledeMacBook-Pro.local>
 2026-03-25 21:01:01 +08:00
Cita 5d2596285b fix: truncate collapsed route group regex badge (#279) 
Co-authored-by: apple <apple@appledeMacBook-Pro.local>
 2026-03-25 20:37:53 +08:00
Cita 639c387532 [codex] fix responses lifecycle parity and codex session serialization (#278) 
* fix responses lifecycle parity

* remove websocket test debug logging

* fix responses proxy stream typecheck

* update compact upstream response expectations

* add community and deepwiki badges

* update linuxdo banner link

* fix responses review follow-ups

* preserve whitespace in responses terminal deltas

* fix responses stream reconciliation edges

* fix responses lifecycle parity and codex session serialization

* fix review follow-up edge cases

---------

Co-authored-by: apple <apple@appledeMacBook-Pro.local>
 2026-03-25 18:56:36 +08:00
Sean Lee 9ba4369a83 fix: auto-detect Feishu webhook format and validate response body (#271) 
* feat: Preserve manual models during discovery and refresh, and add Claude configuration files and project documentation.feat: Preserve manual models during discovery and refresh, and add Claude configuration and project documentation files.

* fix: fix Feishu and Larksuite webhook support to the notification service with updated UI and tests.

---------

Co-authored-by: Xiang Li <xiangli>
 2026-03-25 18:30:32 +08:00
ZhengYiTao dc40edf8e8 fix: case-insensitive model merging and disabled model matching (#251) 
* fix: MySQL-compatible case-insensitive model merge and disabled model matching

Root cause: MySQL uses utf8mb4_general_ci collation by default, making the
unique index on (account_id, model_name) case-insensitive. When different
tokens discover the same model with different casing (e.g., 'GPT-4o' vs
'gpt-4o'), the case-sensitive JavaScript Set allowed both, but the MySQL
batch INSERT failed with a duplicate key error — causing the entire model
refresh to silently fail and leaving stale routes (including disabled models).

Fixes:
1. mergeDiscoveredModels: change Set<string> to Map<lowercase, original>
   for cross-scan dedup, matching normalizeModels' existing behavior.
2. isModelDisabledForSite: compare with toLowerCase() so disabled models
   are filtered regardless of case variants across discovery sources.
3. tokens.ts /api/routes/rebuild: add missing await on
   rebuildTokenRoutesFromAvailability() so errors propagate correctly
   instead of being silently swallowed.

* fix: add missing await on rebuildTokenRoutesFromAvailability in stats.ts

The POST handler for /api/models/check/:accountId called
rebuildTokenRoutesFromAvailability() without await, returning a Promise
object in the response instead of the actual rebuild result.
 2026-03-25 11:22:37 +08:00
Cita 709f528bd2 fix responses lifecycle parity (#272) 
* fix responses lifecycle parity

* remove websocket test debug logging

* fix responses proxy stream typecheck

* update compact upstream response expectations

* add community and deepwiki badges

* update linuxdo banner link

* fix responses review follow-ups

* preserve whitespace in responses terminal deltas

* fix responses stream reconciliation edges

---------

Co-authored-by: apple <apple@appledeMacBook-Pro.local>
 2026-03-24 23:12:35 +08:00
Sean Lee 3e0083582e feat: Preserve manual models during discovery and refresh, and add Claude configuration files and project documentation.feat: Preserve manual models during discovery and refresh, and add Claude configuration and project documentation files. (#270) 
Co-authored-by: Xiang Li <xiangli>
 2026-03-24 20:01:48 +08:00
Bainily 9cf3dd1904 feat(proxy): improve channel failover stability and sticky session coordination / 优化代理通道故障切换与粘滞会话协调 (#268) 
* wip: preserve local changes before upstream merge

* Improve proxy routing stability and add stable-first strategy

* Sync explicit-group routing strategy to eligible source routes

* Fix proxy retry and runtime health review issues

* fix: make proxy channel retry attempts configurable

* fix: harden proxy retry recovery and bookkeeping

* fix: address pr 257 review comments

* feat(proxy): add sticky session channel coordination

---------

Co-authored-by: Cita <juricek.chen@gmail.com>
 2026-03-24 19:40:44 +08:00
Cita 5b9c83f830 fix: default downstream key access selections to all (#263) 
* fix: default downstream key access selections to all

* test: fix downstream keys test renderer typing
 2026-03-23 22:48:15 +08:00
Cita 4a3b4a8bb6 fix: preserve protocol parity across compatibility hops (#259) 
* wip: preserve local changes before upstream merge

* Improve proxy routing stability and add stable-first strategy

* Sync explicit-group routing strategy to eligible source routes

* Fix proxy retry and runtime health review issues

* fix: make proxy channel retry attempts configurable

* fix: harden proxy retry recovery and bookkeeping

* fix: address pr 257 review comments

* fix: preserve oe tool_result structure

* fix: preserve protocol parity across compatibility hops

* fix: satisfy server build and typecheck

* fix: preserve codex and mcp fallback semantics

* fix: address ci and review follow-ups

---------

Co-authored-by: bnvnvnv <bnvnvnv@gmail.com>
 2026-03-23 20:25:20 +08:00
Cita b3869c4f55 fix: avoid armv7 desktop postinstall in docker build (#262) 2026-03-23 20:24:37 +08:00
Cita b07b16c942 fix: restore docker builder install deps (#261) 
* fix: exclude runtime db config from backup and migration

* fix: restore docker builder install deps
 2026-03-23 20:12:16 +08:00
Cita c838e3263b fix: exclude runtime db config from backup and migration (#260) 2026-03-23 20:05:00 +08:00
Bainily 1449f08e6c fix: stabilize Codex continuation and proxy retry recovery / 修复 Codex 续传与代理重试稳定性 (#257) 
* wip: preserve local changes before upstream merge

* Improve proxy routing stability and add stable-first strategy

* Sync explicit-group routing strategy to eligible source routes

* Fix proxy retry and runtime health review issues

* fix: make proxy channel retry attempts configurable

* fix: harden proxy retry recovery and bookkeeping

* fix: address pr 257 review comments

---------

Co-authored-by: Cita <juricek.chen@gmail.com>
 2026-03-23 19:17:22 +08:00
Cita 5be5e2eb07 fix: preserve protocol parity across Claude fallbacks (#256) 
* fix: preserve protocol parity across claude fallbacks

* fix: tighten protocol parity across responses and anthropic fallbacks

* fix: preserve stricter tool contracts across fallbacks

* fix: unblock anthropic stream server build
 2026-03-23 17:29:49 +08:00
Cita 2940b003af Merge pull request #255 from cita-777/codex/ci-typecheck-pr 
fix: tighten CI typecheck coverage
 2026-03-23 16:40:52 +08:00
Cita 653b7557a7 fix: address review followups 2026-03-23 16:24:31 +08:00
Cita 4b903fdd3b fix: tighten ci typecheck coverage 2026-03-23 16:02:13 +08:00
Cita 40c8c1c7ad Merge pull request #244 from cita-777/codex/single-source-consolidation 
refactor: consolidate single-source routing and protocol helpers
 2026-03-23 15:28:44 +08:00
Cita 764b9aa0e6 fix: address latest coderabbit review findings 2026-03-23 15:24:00 +08:00
Cita 426d9a538d test: relax token selection count assertion 2026-03-23 14:51:57 +08:00
Cita 4686c558aa Merge origin/main into codex/single-source-consolidation 2026-03-23 14:44:52 +08:00
Cita bf969c136a docs: capture full-scope consolidation finish 2026-03-23 14:32:11 +08:00
Cita f9316784aa fix: align final verification scripts and expectations 2026-03-23 14:29:44 +08:00
Cita 7cc0a04b8b refactor: share responsive filter panel scaffold 2026-03-23 14:29:11 +08:00
Cita dd914b327c refactor: extract downstream key drawer 2026-03-23 14:28:37 +08:00
Cita 8e001508bf refactor: extract model tester composer and tighten shared types 2026-03-23 13:44:52 +08:00
Cita 8f14540549 refactor: extract model tester debug panel 2026-03-23 13:35:42 +08:00
Cita 9b21ed3fed refactor: extract account model management modal 2026-03-23 13:32:55 +08:00
Cita c3e3985b6e refactor: extract remaining settings modals 2026-03-23 13:29:39 +08:00
Cita 62eca41bc2 refactor: extract settings portal modals 2026-03-23 13:18:37 +08:00
Cita f7a7084278 refactor: share responsive batch actions across admin pages 2026-03-23 13:12:06 +08:00
Cita b82d7c31d9 refactor: derive legacy schema compat from feature specs 2026-03-23 13:04:09 +08:00
Cita 55aea6afc4 refactor: separate brand registry from BrandIcon 2026-03-23 12:44:38 +08:00
Cita 8b3653c7c9 refactor: share schema metadata normalization rules 2026-03-23 12:23:04 +08:00
Cita 86518202fa refactor: move platform discovery out of model service 2026-03-23 12:14:22 +08:00
Cita 50c34b8866 refactor: keep downstream client metadata on cli profiles 2026-03-23 12:02:44 +08:00
Cita 3877f3a3f1 refactor: centralize oauth identity and route refresh workflow 2026-03-23 11:53:59 +08:00
Cita 328b492ab3 fix: finish review-driven single-source cleanup 2026-03-23 11:26:01 +08:00
Cita a3b061b60f Merge pull request #245 from cita-777/codex/site-binding-conflict 
fix: handle duplicate site binding conflicts
 2026-03-23 09:20:58 +08:00
Cita f5892b9656 Merge pull request #241 from Hureru/feat/model-filter-system 
feat: add model filter system and route page performance optimization
 2026-03-23 00:19:29 +08:00
Cita 90e9140c70 fix: preserve site disabled models on partial load failure 2026-03-22 23:58:43 +08:00
Cita 29c9fcbd29 fix: resolve remaining review follow-ups 2026-03-22 23:53:41 +08:00
Cita 5d78658af9 fix: address review feedback and code scanning alerts 2026-03-22 23:41:45 +08:00
Hureru 9a5e2bbc60 fix: prevent brand list loading indicator from hanging on API failure 2026-03-22 23:13:51 +08:00
Cita daa6a01ccf fix: handle duplicate site binding conflicts 2026-03-22 22:18:44 +08:00
Cita 32d7037629 refactor: share platform file and route helpers 2026-03-22 22:17:50 +08:00
Cita 9290e51ecc refactor: consolidate single-source routing and protocol helpers 2026-03-22 21:27:09 +08:00
Cita 96e7614835 fix: trust proxy headers and align proxy file mysql indexes 2026-03-22 21:17:56 +08:00
Hureru d278b41be2 fix: address review issues in brand filter sync, model guard, route counts, and candidate loading 
- Sync blockedBrands local state after save to prevent stale chips
- Defer getBrandList from blocking Settings bootstrap
- Guard model management UI on brandGroups instead of availableModels
- Deduplicate single-model add in disabled models
- Skip read-only/zero-channel routes in enabledCounts and filter
- Add sequence counter to loadCandidates to prevent force race condition
- Use stableAddChannel for mobile add-channel button
 2026-03-22 20:44:55 +08:00
Hureru b8ad89d1ab fix: use ref-based stale guard for site disabled-models fetch 
Replace closure-captured editor check with loadingModelsSiteIdRef so the
stale-response guard works correctly across rapid site switches. Also
gate setDisabledModelsLoading(false) behind the same ref check.
 2026-03-22 20:26:45 +08:00
Hureru 26be7c024a fix: address review issues across settings, sites, brand matcher, and token routes 
- settings.ts: trigger route rebuild after globalBlockedBrands changes in both
  import and PUT handler; reject non-array payloads with 400 instead of silently
  defaulting to empty array
- sites.ts: trim model names before deduplication so whitespace variants merge
- brandMatcher.ts: align boundary regex with frontend delimiter class [/:_\-\s]
- Settings.tsx: add role="switch" and aria-checked to brand filter chips; make
  getBrandList best-effort so its failure doesn't block page load
- Sites.tsx: build brandGroups from union of availableModels and disabledModels
  so legacy/removed models remain visible; add stale-response guard and error
  logging for disabled/available model fetches
- TokenRoutes.tsx: use baseFilteredRoutes.length for totalRouteCount to keep
  enabled/disabled counts in sync with status filter; add candidatesVersionRef
  to invalidate lazy caches on payload change; add per-channel in-flight guard
  on toggle; invalidate channel cache after rebuild and site-block operations
 2026-03-22 20:18:50 +08:00
Hureru 911d76fa08 fix: add channel toggle and site-block buttons to mobile channel row 2026-03-22 19:27:43 +08:00
Hureru 2f8dae70c2 fix: add missing onToggleChannelEnabled and onSiteBlockModel props to mobile RouteCard 2026-03-22 19:18:44 +08:00
Hureru 3195282c4e fix: address review issues in TokenRoutes performance optimization 
- Escape modelName/siteName in innerHTML to prevent XSS
- Use content-based routePatternsKey for cache invalidation instead of
  length-only keys that miss content changes
- Extract shared baseFilteredRoutes to eliminate duplicated filter logic
  between enabledCounts and filteredRoutes
- Add candidatesPromiseRef to deduplicate concurrent loadCandidates calls
 2026-03-22 19:12:50 +08:00
Hureru 92fd5e034d perf: defer token-candidates loading and lazy-compute heavy route indices 
The routes page loaded ~924KB of API data upfront (summary 366KB +
token-candidates 558KB), but token-candidates was only needed when
expanding cards, opening panels, or using filters. This caused a ~3s
element render delay blocking LCP.

Changes:
- Split load() so first paint only fetches routesSummary (366KB)
- Preload token-candidates in background via requestIdleCallback
- Wrap candidates state updates in startTransition to avoid UI jank
- Convert 3 heavy O(routes×models) useMemo indices to lazy per-route
  computation with ref-based cache (candidateIndex, missingTokenIndex,
  missingTokenGroupIndex)
- Guard 4 ManualRoutePanel-only useMemos with showManual check
- Convert 2 derived useMemos to per-route getter functions
- Add loadCandidates() calls at 7 interaction trigger points
 2026-03-22 19:00:03 +08:00
Hureru d2db989b98 fix: add bottom border to channel rows for clearer separation 2026-03-22 19:00:02 +08:00
Hureru 835fccb4f5 fix: align site-block and delete buttons in channel row grid layout 
Wrap site-block and delete buttons in a flex container and expand grid
to 4 columns so all action buttons stay on the same row.
 2026-03-22 18:59:04 +08:00
Hureru 4415317bdc fix: align brand matcher with frontend logic and remove manual model input 
- brandMatcher: port collectBrandCandidates + buildMatchContext from
  frontend BrandIcon.tsx so matching is identical between route display
  and rebuild filtering; segments now split on /,:,\s only (not - or _),
  and candidates are recursively generated from /,:,, splits
- Sites.tsx: remove manual model name input and handleAddDisabledModel;
  the checkbox-based batch selection UI fully replaces it
 2026-03-22 18:55:40 +08:00
Hureru f14ffd7dc9 fix: address review issues in model filter system 
- brandMatcher: split keywords into includes/startsWith/segment/boundary
  modes to align with frontend BrandIcon.tsx matching semantics, preventing
  false-positive blocking from short keywords like o1, tts, command
- handleSiteBlockModel: reject wildcard route patterns (e.g. gpt-*) from
  being written to site disabled list; only allow exact model names
- Sites.tsx: extract brand grouping to useMemo, convert disabledModels
  to Set for O(1) lookup, remove duplicate IIFE computations in JSX
- handleSiteBlockModel: replace window.confirm with project-style DOM
  dialog for visual consistency
- enabledCounts: compute from filtered scope (excluding enabled filter
  itself) so counts reflect current brand/site/search filters
- Fix declaration order: move enabledCounts after sortedRoutes to avoid
  ReferenceError
 2026-03-22 18:55:40 +08:00
Hureru cf6ed7db91 feat: add model filter system with site-level batch disable, global brand filter, route status filter, and channel site-block shortcut 
- Route status filter: add enabled/disabled filter chips to RouteFilterBar
- Channel site-block: add "站点屏蔽" button on channel rows to quickly
  add a model to a site's disabled list and trigger rebuild
- Site batch selection: new GET /api/sites/:id/available-models endpoint;
  Sites.tsx now shows a brand-grouped checkbox list for batch model disable
- Global brand filter: new brandMatcher.ts service; settings API and UI
  for blocking entire brands from route generation
- Fix infinite scroll race condition when sentinel ref is null during
  IntersectionObserver effect setup after filter changes
 2026-03-22 18:55:40 +08:00
Cita 3cc6b7be45 Merge pull request #238 from cita-777/codex/mobile-panel-refactor-final 
feat: overhaul mobile management layouts
 2026-03-21 20:47:56 +08:00
Cita 09fbf258e2 feat: overhaul mobile management layouts 2026-03-21 20:42:25 +08:00
Cita c64a760b69 Merge pull request #237 from cita-777/codex/codex-review-fixes 
fix: harden codex runtime routing and oauth recovery
 2026-03-21 20:40:07 +08:00
Cita a81965176f fix: preserve inactive availability after main merge 2026-03-21 20:34:52 +08:00
Cita 3775ee059c Merge remote-tracking branch 'origin/main' into codex/codex-review-fixes 
# Conflicts:
#	src/server/services/modelService.ts
 2026-03-21 20:31:30 +08:00
Cita fa372d121a fix: preserve availability on inactive refresh failure 2026-03-21 20:27:18 +08:00
Cita 4c14f9c9b0 Merge pull request #234 from cita-777/codex/gemini-oauth-hardening 
Fix Gemini OAuth refresh and failure coverage
 2026-03-21 20:13:08 +08:00
Cita 4480f504e4 fix: satisfy server build typing 2026-03-21 19:58:41 +08:00
Cita d9e550c279 fix: address codex review findings 2026-03-21 19:45:29 +08:00
Cita b7a1e523e7 fix: reuse oauth singleflight in gemini discovery 2026-03-21 19:29:33 +08:00
Cita e09fb43b33 Merge pull request #236 from cita-777/codex/claude-count-models 
Fix Claude count_tokens compatibility and OAuth model discovery
 2026-03-21 19:28:18 +08:00
Cita c7ba436685 Merge pull request #235 from cita-777/codex/gemini-multimodal-routing 
fix: keep gemini multimodal routing off endpoint memory
 2026-03-21 19:27:36 +08:00
Cita 1d8889001f fix: harden codex runtime routing and oauth recovery 2026-03-21 19:07:14 +08:00
Cita dc93c58582 Fix Claude count tokens routing and model discovery 2026-03-21 18:42:28 +08:00
Cita dd48550ffa Fix Gemini OAuth refresh and failure coverage 2026-03-21 18:38:00 +08:00
Cita 500ba25787 fix: bypass multimodal endpoint memory for gemini 2026-03-21 18:37:36 +08:00
Cita 6a19d809f0 Merge pull request #233 from cita-777/codex/login-surface-pr 
feat(web): redesign login surface
 2026-03-21 17:17:51 +08:00
Cita 781c44140f Merge pull request #232 from cita-777/codex/backup-config-semantics-v21 
fix: refine config backup import semantics
 2026-03-21 17:12:53 +08:00
ciat-777 719e21cce7 feat(web): redesign login surface 2026-03-21 17:12:11 +08:00
ciat-777 89d0aba497 fix: refine config backup import semantics 2026-03-21 16:55:32 +08:00
Cita 89d6527aa1 Merge pull request #231 from cita-777/codex/responses-chat-tool-filter 
fix: strip responses-only tools on chat fallback
 2026-03-21 16:44:29 +08:00
ciat-777 7e09ce83b8 fix(proxy): strip responses-only tools on chat fallback 2026-03-21 16:38:46 +08:00
Cita f586d3f318 Merge pull request #229 from cita-777/codex/gemini-claude-identity-encoding 
Codex/gemini claude identity encoding
 2026-03-21 15:55:51 +08:00
ciat-777 5a4f881b95 fix: restore generic inline document endpoint fallbacks 2026-03-21 15:52:22 +08:00
Cita b882b48bc0 Merge pull request #230 from cita-777/codex/backup-preserve-local-stats 
fix: preserve local usage state on backup import
 2026-03-21 15:45:02 +08:00
ciat-777 ab31e0b1c9 fix: preserve local usage state on backup import 2026-03-21 15:41:46 +08:00
ciat-777 7a2953ac36 fix: decode zstd responses while restoring claude encoding 2026-03-21 15:38:11 +08:00
Cita e1f4fde916 Merge pull request #228 from cita-777/codex/fix-pr-115-rebased 
fix(web): polish WebDAV backup form controls
 2026-03-21 14:16:19 +08:00
ciat-777 dbc17f6907 fix(web): polish webdav backup form controls 2026-03-21 14:05:52 +08:00
ciat-777 17a4281117 fix: avoid messages fallback for generic file uploads 2026-03-21 14:03:35 +08:00
Cita d17e80f05e Merge pull request #227 from cita-777/codex/openclaw-user-agent-v2 
fix: detect openclaw user-agent in proxy logs
 2026-03-21 13:56:14 +08:00
ciat-777 272b88c6c8 fix: detect openclaw user-agent in proxy logs 2026-03-21 13:53:02 +08:00
Cita 9395eecfc9 Merge pull request #115 from cita-777/dependabot/npm_and_yarn/drizzle-risk-539e1a854f 
build(deps): bump the drizzle-risk group with 2 updates
 2026-03-21 13:39:49 +08:00
ciat-777 e454ec18ec fix(api): unwrap downstream key unique violations 2026-03-21 13:30:06 +08:00
dependabot[bot] 87cf54140c build(deps): bump the drizzle-risk group with 2 updates 
Bumps the drizzle-risk group with 2 updates: [drizzle-orm](https://github.com/drizzle-team/drizzle-orm) and [drizzle-kit](https://github.com/drizzle-team/drizzle-orm).


Updates `drizzle-orm` from 0.36.4 to 0.45.1
- [Release notes](https://github.com/drizzle-team/drizzle-orm/releases)
- [Commits](https://github.com/drizzle-team/drizzle-orm/compare/0.36.4...0.45.1)

Updates `drizzle-kit` from 0.28.1 to 0.31.9
- [Release notes](https://github.com/drizzle-team/drizzle-orm/releases)
- [Commits](https://github.com/drizzle-team/drizzle-orm/compare/drizzle-kit@0.28.1...drizzle-kit@0.31.9)

---
updated-dependencies:
- dependency-name: drizzle-orm
  dependency-version: 0.45.1
  dependency-type: direct:production
  update-type: version-update:semver-minor
  dependency-group: drizzle-risk
- dependency-name: drizzle-kit
  dependency-version: 0.31.9
  dependency-type: direct:development
  update-type: version-update:semver-minor
  dependency-group: drizzle-risk
...

Signed-off-by: dependabot[bot] <support@github.com>
 2026-03-21 05:17:02 +00:00
Cita 80d4bdf88c Merge pull request #189 from cita-777/dependabot/npm_and_yarn/minor-and-patch-f409002027 
build(deps): bump the minor-and-patch group across 1 directory with 7 updates
 2026-03-21 13:14:44 +08:00
Cita 9b17c3ebdf Merge pull request #159 from Hureru/feat/account-level-proxy 
feat(proxy): account-level proxy URL override
 2026-03-21 13:14:08 +08:00
Cita 8ced774e29 Merge pull request #226 from cita-777/codex/gemini-claude-identity-encoding 
fix: force identity encoding for claude messages
 2026-03-21 12:59:40 +08:00
ciat-777 424e1e210b test: align claude count tokens encoding expectation 2026-03-21 12:56:34 +08:00
ciat-777 1b78359739 fix: force identity encoding for claude messages 2026-03-21 12:48:34 +08:00
ciat-777 04655a8b17 fix(proxy): honor account proxy during oauth discovery 2026-03-21 12:46:46 +08:00
Cita 9007ca7ea7 Merge pull request #224 from cita-777/codex/webdav-backup-armv7l 
Remove armv7 smoke PR check
 2026-03-21 11:55:15 +08:00
ciat-777 a2ef7e07fb Remove armv7 smoke PR check 2026-03-21 11:53:16 +08:00
Cita a7bac92975 Merge pull request #223 from cita-777/codex/proxy-log-self-report-client-name 
fix: prefer self-reported proxy log client names
 2026-03-21 11:52:48 +08:00
ciat-777 7c9bdc51c7 fix: prefer self-reported proxy log client names 2026-03-21 11:48:15 +08:00
Hureru 4d0c4b8129 feat(proxy): propagate account-level proxy across all surfaces 
- chatSurface/openAiResponsesSurface: extract channelProxyUrl once and pass to withSiteRecordProxyRequestInit
- geminiSurface: switch from withSiteProxyRequestInit to withSiteRecordProxyRequestInit with channelProxyUrl
- balanceService: pass accountProxyUrl to sub2api token refresh requests
- siteProxy: fix isAccountOverride to only be true when account proxy differs from site proxy
- Accounts.tsx: use parseAccountExtraConfig helper for proxy badge display
 2026-03-21 11:44:57 +08:00
Hureru 8df3b1431f Merge remote-tracking branch 'origin/main' into feat/account-level-proxy 
# Conflicts:
#	src/server/proxy-core/surfaces/chatSurface.ts
#	src/server/proxy-core/surfaces/openAiResponsesSurface.ts
#	src/server/routes/proxy/embeddings.ts
#	src/server/routes/proxy/images.ts
#	src/server/services/modelService.ts
 2026-03-21 10:09:19 +08:00
Cita 4ba7749391 Merge pull request #220 from cita-777/codex/webdav-backup-armv7l 
Add WebDAV backup sync and armv7 Docker builds
 2026-03-21 01:24:51 +08:00
Cita 3be452d794 Merge pull request #219 from cita-777/codex/latest-main-protocol-review 
[codex] fix modeltester attachment replay and add proxy file retention
 2026-03-21 01:10:36 +08:00
ciat-777 0574fa93b3 Isolate server Docker build from desktop deps 2026-03-21 01:09:50 +08:00
ciat-777 7c227d8365 Handle replay hydration file fetch timeouts 2026-03-21 01:03:03 +08:00
ciat-777 89282093a9 Use armv7-compatible Node Docker base 2026-03-21 00:59:23 +08:00
ciat-777 1ce036fd46 Address PR review for WebDAV and armv7 2026-03-21 00:48:42 +08:00
ciat-777 bc52b6b5fd Add WebDAV backup sync and armv7 Docker builds 2026-03-21 00:06:16 +08:00
cita 95bf8df499 fix modeltester attachment replay and add proxy file retention 2026-03-21 00:04:06 +08:00
Cita 94b6cac871 Merge pull request #218 from cita-777/codex/modeltester-attachment-review-fixes 
[codex] Fix model tester attachment replay and capability gating
 2026-03-20 23:12:43 +08:00
Cita 44c485752d Merge pull request #217 from cita-777/codex/sqlite-site-announcements-migration-fixes 
[codex] fix sqlite bootstrap and site announcement migration
 2026-03-20 23:12:06 +08:00
cita 78f6c5b2cc Merge origin/main into codex/modeltester-attachment-review-fixes 2026-03-20 23:09:27 +08:00
cita 4369aeb1cb fix model tester attachment replay and capability gating 2026-03-20 22:56:01 +08:00
cita 9bc804c121 fix sqlite bootstrap and site announcement migration 2026-03-20 22:51:57 +08:00
Cita 79146af16a Merge pull request #216 from cita-777/codex/fix-responses-endpoint-memory 
[codex] fix cross-protocol conversation file compatibility
 2026-03-20 21:53:13 +08:00
cita 2890b7daf3 fix cross-protocol conversation file compatibility 2026-03-20 21:48:05 +08:00
Cita a2a93abb69 Merge pull request #214 from zmoon460/main 
Fix: postgres 环境下无法保存 模型白名单和群组选择
 2026-03-20 21:21:44 +08:00
Cita 485e7a0e7c Merge pull request #215 from Brucents/fix/direct-credential-route-binding 
fix(routes): dedupe direct credentials and clarify binding labels
 2026-03-20 21:19:48 +08:00
Brucents 5ee493778f fix(routes): dedupe direct credentials and clarify binding labels 2026-03-20 20:41:32 +08:00
zmoon460 da76f56721 Refactor parseJson to handle different value types 
Refactor parseJson function to handle various input types and improve null checks.
 2026-03-20 20:10:12 +08:00
zmoon460 ade5e0b1b3 Enhance unique violation check for PostgreSQL 2026-03-20 20:08:56 +08:00
Cita 0d70dba4e6 Merge pull request #212 from Brucents/fix/proxy-upstream-resolution 
fix(proxy): 修正代理上游解析并补齐系统代理测试能力
 2026-03-20 19:21:30 +08:00
Cita 1758d70b55 Merge pull request #211 from cita-777/codex/fix-responses-endpoint-memory 
[codex] fix responses endpoint memory
 2026-03-20 19:21:11 +08:00
cita 5f744c3382 fix responses endpoint memory 2026-03-20 19:15:53 +08:00
Brucents 088d0455a9 fix(proxy): add system proxy connectivity test and align proxy UI copy 2026-03-20 19:13:23 +08:00
Brucents a66cbafeb8 fix(proxy): separate upstream target resolution from proxy dispatch and add site-level proxy URLs 2026-03-20 17:40:02 +08:00
Cita 8c5ecc26d1 Merge pull request #207 from cita-777/codex/issue-200-group-route-alias 
[codex] fix explicit-group source-model fallback
 2026-03-20 16:55:28 +08:00
cita 3601e7a708 fix explicit-group source-model fallback 2026-03-20 16:45:19 +08:00
Cita 112191c5bc Merge pull request #206 from cita-777/codex/proxy-logs-model-badge-width 
[codex] match proxy log model badge width to model name
 2026-03-20 16:32:17 +08:00
cita 1a0e22b767 fix: match proxy log model badge width to content 2026-03-20 16:30:24 +08:00
Cita 400f3e1dfc fix: use tidb-compatible mysql datetime defaults (#205) 2026-03-20 16:21:37 +08:00
Bainily e9c1bd898e [codex] improve proxy stability, routing, and site subscription visibility (#194) 
* wip: preserve local changes before upstream merge

* Improve proxy routing stability and add stable-first strategy
 2026-03-20 16:18:28 +08:00
Shinku e2595bcab3 Merge pull request #204 from Shinku-Chen/rand-sk-2 
生成密钥的时候,能随机生成,同时能复制token
 2026-03-20 16:17:51 +08:00
Cita 5e872b331e Merge pull request #202 from cita-777/codex/site-announcement-postgres-time-fix 
[codex] unify external db datetime behavior
 2026-03-20 15:49:13 +08:00
Cita aad21e5b33 Merge pull request #201 from cita-777/codex/fix-client-detection 
[codex] improve downstream client detection
 2026-03-20 15:42:28 +08:00
cita 1451e61557 fix: unify external db datetime behavior 2026-03-20 15:39:41 +08:00
cita 0068200f2d Improve downstream client detection 2026-03-20 15:31:21 +08:00
Cita 03a3db84c1 Merge pull request #195 from cita-777/codex/site-announcement-timezone-fix 
[codex] prefer client timezone for site announcements
 2026-03-20 14:18:01 +08:00
cita f880e3a25f prefer client timezone for site announcements 2026-03-20 14:06:11 +08:00
Cita a2caa94069 Merge pull request #191 from cita-777/codex/checkin-settings-ui-fix 
[codex] fix checkin settings styling and empty updates
 2026-03-20 13:35:17 +08:00
Cita fe99968602 Merge pull request #190 from cita-777/codex/site-announcement-timezone-fix 
[codex] fix site announcement timezone
 2026-03-20 13:33:12 +08:00
cita 4f94393806 fix checkin settings styling and empty updates 2026-03-20 13:31:26 +08:00
cita 1af1fe244a fix site announcement timezone 2026-03-20 13:26:55 +08:00
dependabot[bot] 8b47df55ec build(deps): bump the minor-and-patch group across 1 directory with 7 updates 
Bumps the minor-and-patch group with 6 updates in the / directory:

| Package | From | To |
| --- | --- | --- |
| [@visactor/react-vchart](https://github.com/VisActor/VChart/tree/HEAD/packages/react-vchart) | `2.0.16` | `2.0.19` |
| [mysql2](https://github.com/sidorares/node-mysql2) | `3.18.2` | `3.20.0` |
| [nodemailer](https://github.com/nodemailer/nodemailer) | `8.0.1` | `8.0.3` |
| [@tailwindcss/vite](https://github.com/tailwindlabs/tailwindcss/tree/HEAD/packages/@tailwindcss-vite) | `4.2.1` | `4.2.2` |
| [electron](https://github.com/electron/electron) | `41.0.2` | `41.0.3` |
| [mermaid](https://github.com/mermaid-js/mermaid) | `11.12.3` | `11.13.0` |



Updates `@visactor/react-vchart` from 2.0.16 to 2.0.19
- [Release notes](https://github.com/VisActor/VChart/releases)
- [Changelog](https://github.com/VisActor/VChart/blob/develop/packages/react-vchart/CHANGELOG.md)
- [Commits](https://github.com/VisActor/VChart/commits/v2.0.19/packages/react-vchart)

Updates `mysql2` from 3.18.2 to 3.20.0
- [Release notes](https://github.com/sidorares/node-mysql2/releases)
- [Changelog](https://github.com/sidorares/node-mysql2/blob/master/Changelog.md)
- [Commits](https://github.com/sidorares/node-mysql2/compare/v3.18.2...v3.20.0)

Updates `nodemailer` from 8.0.1 to 8.0.3
- [Release notes](https://github.com/nodemailer/nodemailer/releases)
- [Changelog](https://github.com/nodemailer/nodemailer/blob/master/CHANGELOG.md)
- [Commits](https://github.com/nodemailer/nodemailer/compare/v8.0.1...v8.0.3)

Updates `@tailwindcss/vite` from 4.2.1 to 4.2.2
- [Release notes](https://github.com/tailwindlabs/tailwindcss/releases)
- [Changelog](https://github.com/tailwindlabs/tailwindcss/blob/main/CHANGELOG.md)
- [Commits](https://github.com/tailwindlabs/tailwindcss/commits/v4.2.2/packages/@tailwindcss-vite)

Updates `electron` from 41.0.2 to 41.0.3
- [Release notes](https://github.com/electron/electron/releases)
- [Commits](https://github.com/electron/electron/compare/v41.0.2...v41.0.3)

Updates `mermaid` from 11.12.3 to 11.13.0
- [Release notes](https://github.com/mermaid-js/mermaid/releases)
- [Commits](https://github.com/mermaid-js/mermaid/compare/mermaid@11.12.3...mermaid@11.13.0)

Updates `tailwindcss` from 4.2.1 to 4.2.2
- [Release notes](https://github.com/tailwindlabs/tailwindcss/releases)
- [Changelog](https://github.com/tailwindlabs/tailwindcss/blob/main/CHANGELOG.md)
- [Commits](https://github.com/tailwindlabs/tailwindcss/commits/v4.2.2/packages/tailwindcss)

---
updated-dependencies:
- dependency-name: "@visactor/react-vchart"
  dependency-version: 2.0.19
  dependency-type: direct:production
  update-type: version-update:semver-patch
  dependency-group: minor-and-patch
- dependency-name: mysql2
  dependency-version: 3.20.0
  dependency-type: direct:production
  update-type: version-update:semver-minor
  dependency-group: minor-and-patch
- dependency-name: nodemailer
  dependency-version: 8.0.3
  dependency-type: direct:production
  update-type: version-update:semver-patch
  dependency-group: minor-and-patch
- dependency-name: "@tailwindcss/vite"
  dependency-version: 4.2.2
  dependency-type: direct:development
  update-type: version-update:semver-patch
  dependency-group: minor-and-patch
- dependency-name: electron
  dependency-version: 41.0.3
  dependency-type: direct:development
  update-type: version-update:semver-patch
  dependency-group: minor-and-patch
- dependency-name: mermaid
  dependency-version: 11.13.0
  dependency-type: direct:development
  update-type: version-update:semver-minor
  dependency-group: minor-and-patch
- dependency-name: tailwindcss
  dependency-version: 4.2.2
  dependency-type: direct:development
  update-type: version-update:semver-patch
  dependency-group: minor-and-patch
...

Signed-off-by: dependabot[bot] <support@github.com>
 2026-03-20 04:56:06 +00:00
Cita 029ee10d26 Merge pull request #187 from cita-777/codex/proxy-log-client-detection-main 
feat: add proxy log client detection filters
 2026-03-20 12:51:53 +08:00
Cita a4cb362599 Merge pull request #188 from cita-777/codex/site-announcements 
[codex] improve site announcement display
 2026-03-20 12:51:31 +08:00
cita 8291b9c59f test: align proxy route db mocks with client columns 2026-03-20 12:49:09 +08:00
cita f0d9936bf0 improve site announcement display 2026-03-20 12:45:11 +08:00
Cita a75d0c2a70 Merge pull request #186 from cita-777/codex/issues-180-160-31 
[codex] fix desktop tray icon, telegram topics, and checkin intervals
 2026-03-20 12:26:52 +08:00
cita 4e60290838 feat: add proxy log client detection filters 2026-03-20 12:25:30 +08:00
cita 220f786204 fix desktop tray icon telegram topics and checkin intervals 2026-03-20 12:23:13 +08:00
Cita 2de5eebf29 Merge pull request #179 from Shinku-Chen/tg-proxy 
增加TG代理选项
 2026-03-20 11:40:29 +08:00
Cita 08e7b052da Merge pull request #185 from cita-777/codex/site-announcements 
[codex] add site announcements
 2026-03-20 11:28:33 +08:00
Cita 0f5ec9a1c1 Merge pull request #184 from cita-777/codex/full-cliproxyapi-parity 
[codex] complete codex cliproxyapi parity
 2026-03-20 11:28:24 +08:00
cita 940bc1d71c add site announcements 2026-03-20 11:24:29 +08:00
cita adc4fb1be7 complete codex cliproxyapi parity 2026-03-20 11:23:29 +08:00
Cita 2a4502a539 Merge pull request #182 from cita-777/codex/downstream-key-whitelist-select-all-persistence 
[codex] fix downstream key whitelist select-all persistence
 2026-03-20 11:01:30 +08:00
cita 9077703503 fix downstream key whitelist select-all persistence 2026-03-20 10:54:02 +08:00
Shinku c5d55f0ab0 增加TG代理选项,增加测试用例 2026-03-20 01:03:21 +08:00
Shinku 54203d64a3 增加TG代理选项 2026-03-20 00:57:40 +08:00
Cita 5a9f007a75 Merge pull request #178 from cita-777/codex/downstream-key-default-deny-select-all 
[codex] default deny empty downstream key exposure
 2026-03-20 00:42:43 +08:00
cita 77d6a415d1 fix managed downstream deny-all semantics 2026-03-20 00:39:39 +08:00
cita 5403a946c6 default deny empty downstream key exposure 2026-03-20 00:22:17 +08:00
Cita ee6eeaddeb Merge pull request #177 from cita-777/codex/fix-responses-eof-false-success-clean 
[codex] Handle mislabeled responses SSE bodies
 2026-03-19 23:27:55 +08:00
cita 8672ff8dff Handle mislabeled responses SSE bodies 2026-03-19 23:20:40 +08:00
Hureru 382c6b22d8 Merge remote-tracking branch 'origin/main' into feat/account-level-proxy 
# Conflicts:
#	src/server/routes/proxy/chat.ts
#	src/server/routes/proxy/responses.ts
 2026-03-19 23:18:41 +08:00
Cita 50e3c868d0 Merge pull request #174 from cita-777/codex/fix-responses-eof-false-success-clean 
[codex] fix responses empty completion handling
 2026-03-19 22:37:27 +08:00
cita 2f0ee4d648 fix responses empty completion handling 2026-03-19 22:22:02 +08:00
Cita 97f72464a3 Merge pull request #171 from cita-777/codex/fix-responses-eof-false-success-clean 
fix: stop false success logging when responses streams end early
 2026-03-19 21:09:42 +08:00
Cita 0c4da8329d Merge pull request #170 from cita-777/codex/release-mac-arch-guard-main-20260319 
[codex] harden mac release architecture verification
 2026-03-19 21:00:35 +08:00
Cita 882c9dee5a fix: harden mac release architecture verification 2026-03-19 20:49:24 +08:00
Cita e656179044 fix: harden mac release architecture verification 2026-03-19 20:49:23 +08:00
Cita 1607928b6c fix: harden mac release architecture verification 2026-03-19 20:49:22 +08:00
Cita 6c3a09da86 fix: harden mac release architecture verification 2026-03-19 20:49:21 +08:00
cita 8f0b5c81f4 fix responses eof false success logging 2026-03-19 20:43:44 +08:00
Cita 36e9a85664 fix backup import preview and refresh race (#167) 2026-03-19 17:14:07 +08:00
Cita 24483c28eb Refactor proxy-core surfaces and transformer boundaries (#163) 
* refactor: add canonical request contracts

* test: harden transformer boundary contracts

* refactor: adapt protocol transformers to canonical contract

* refactor: add cli profile registry

* refactor: extract provider profiles

* refactor: add conductor and provider executors

* refactor: add models surface

* refactor: migrate responses surface

* refactor: migrate chat surface

* refactor: migrate gemini surface

* refactor: migrate file surfaces

* test: align runtime executor undici mock

* fix: preserve compact SSE closeout payloads

* feat: support all-api-hub v2 backup imports

* fix: aggregate codex oauth SSE final payloads

* fix: harden responses SSE failure handling
 2026-03-19 16:07:56 +08:00
Hureru 7c6b729ce1 fix(proxy): preserve requestedModel fallback in embeddings forwardBody 2026-03-19 01:48:52 +08:00
Hureru bef1cd05ea fix(proxy): apply account proxy to image edits route 2026-03-19 01:47:39 +08:00
Hureru 028a767639 fix(proxy): apply account proxy to balance refresh and income fallback calls 2026-03-19 01:45:15 +08:00
Hureru 471879abbf fix(proxy): apply account proxy to OAuth model discovery calls 2026-03-19 01:43:22 +08:00
Hureru bece34ae5b fix(proxy): skip dispatcher cache for account-level proxy URLs 2026-03-19 01:39:35 +08:00
Hureru 619df14291 fix(proxy): apply account-level proxy to count_tokens and completions routes 2026-03-19 01:30:37 +08:00
Hureru 17afe3319e fix(proxy): fix merge conflict data loss in embeddings.ts success path 2026-03-19 01:21:00 +08:00
Hureru 849800c4cd feat(web): use purple badge capsule for account proxy indicator 2026-03-19 01:12:39 +08:00
Hureru 252d40d897 fix(proxy): fix merge conflict syntax error in images.ts catch block 2026-03-19 00:48:12 +08:00
Cita c0c993f448 fix: align explicit group route picker and details (#158) 
* fix: align explicit group route picker and details

* fix: move responses stream closeout into transformer facade
 2026-03-19 00:47:22 +08:00
Hureru f064921757 Merge remote-tracking branch 'origin/main' into feat/account-level-proxy 
# Conflicts:
#	src/server/routes/proxy/completions.ts
#	src/server/services/siteProxy.ts
 2026-03-19 00:00:10 +08:00
Hureru 803ba84cfd Merge branch 'main' into feat/account-level-proxy 
# Conflicts:
#	src/server/routes/api/accountTokens.ts
#	src/server/routes/proxy/chat.ts
#	src/server/routes/proxy/completions.ts
#	src/server/routes/proxy/embeddings.ts
#	src/server/routes/proxy/endpointFlow.ts
#	src/server/routes/proxy/images.ts
#	src/server/routes/proxy/responses.ts
#	src/server/services/accountExtraConfig.test.ts
#	src/server/services/modelService.ts
 2026-03-18 23:42:21 +08:00
xuyufengfei 45fe687c0d 增加了空回为失败和自定义失败关键词的功能，修复了机器人提出的问题 (#153) 
* Add proxy failure rules for keywords and empty responses

* fix(proxy): detect failure keywords for streamed chat responses

* Fix(tester): treat empty stream output as error

* feat(server): default listen host to IPv6 any-address

* fix(proxy): treat empty upstream content as failure

* Revert "feat(server): default listen host to IPv6 any-address"

This reverts commit 2ca49a3891cc3a2e37138156b17b660b6a3cb7ea.

* fix(settings): validate proxy failure settings

* fix: address CodeRabbit feedback in proxy failure detection

* test: force NODE_ENV=test for vitest to avoid React act() prod build

* fix(proxy/chat): preserve true SSE streaming (no upstream.text buffering)

* fix: avoid http fallback after hijacked SSE stream

* fix: wire proxy failure detection into chat and responses

---------

Co-authored-by: metapi-bot <metapi-bot@local>
Co-authored-by: openclaw <bot@local>
Co-authored-by: openclaw <openclaw@local>
Co-authored-by: openclaw-executor <executor@openclaw.local>
Co-authored-by: xuyufengfei <xuyufengfei@users.noreply.github.com>
Co-authored-by: cita <juricek.chen@gmail.com>
 2026-03-18 22:43:13 +08:00
Brucents 2a51ef6e4a fix: 支持 SOCKS5 系统代理并修复脱敏令牌重复同步 (#154) 
* fix: 支持 SOCKS5 系统代理并修复脱敏令牌重复同步

* fix: 避免复用完全模糊的脱敏令牌

* fix: 修复 reviewer 反馈的令牌同步与 SOCKS5 问题

* fix: avoid masked token sync collisions

---------

Co-authored-by: Brucents <mail@urlk.cn>
Co-authored-by: cita <juricek.chen@gmail.com>
 2026-03-18 22:41:39 +08:00
Cita a71ffb3641 Merge pull request #155 from cita-777/codex/fix-connection-and-release-regressions 
[codex] fix route grouping and codex websocket regressions
 2026-03-18 21:49:30 +08:00
cita c989a029ab fix: recover sqlite migration gaps and harden route regex 2026-03-18 21:45:07 +08:00
cita efe60d7cc2 refactor: streamline explicit group editor flow 2026-03-18 21:21:38 +08:00
cita f769f43909 fix route grouping and codex websocket regressions 2026-03-18 20:38:01 +08:00
Cita f7881796d4 Merge pull request #151 from cita-777/codex/fix-connection-and-release-regressions 
[codex] fix connection and release regressions
 2026-03-18 18:43:51 +08:00
cita 332007d4fb fix responses stream failure logging 2026-03-18 18:17:06 +08:00
cita 38e46e165b fix connection and release regressions 2026-03-18 18:00:59 +08:00
Cita d928e067c1 Merge pull request #150 from cita-777/fix/codex-responses-runtime-parity 
fix: harden codex runtime header forwarding
 2026-03-18 15:17:43 +08:00
ciat-777 5372668c44 fix: minimize codex upstream headers and clean quota wording 2026-03-18 14:58:01 +08:00
Cita 428af17250 Merge pull request #149 from cita-777/fix/codex-responses-runtime-parity 
fix: align codex responses continuity handling
 2026-03-18 13:28:28 +08:00
ciat-777 90f0c30861 fix: align codex responses continuity handling 2026-03-18 13:25:42 +08:00
Cita 131fef6373 Merge pull request #147 from cita-777/feat/proxy-runtime-parity 
feat: extend proxy runtime parity
 2026-03-18 12:48:44 +08:00
ciat-777 f902fe1cf6 feat: surface oauth quota details 2026-03-18 12:42:31 +08:00
ciat-777 cd37b11722 feat: extend proxy runtime parity 2026-03-18 12:01:50 +08:00
Cita 20ef75e76d Merge pull request #146 from cita-777/fix/oauth-onboarding-reliability 
fix: improve oauth onboarding reliability
 2026-03-18 00:39:01 +08:00
ciat-777 0516c09c32 fix: align antigravity model discovery request headers 2026-03-18 00:31:32 +08:00
ciat-777 c12da45dfd fix: improve oauth onboarding reliability 2026-03-18 00:03:55 +08:00
Cita e223f24d1a Merge pull request #144 from cita-777/fix/oauth-onboarding-cliproxyapi 
fix: align oauth onboarding with cliproxyapi
 2026-03-18 00:02:10 +08:00
ciat-777 d4987bea84 fix: align oauth onboarding with cliproxyapi 2026-03-17 23:47:56 +08:00
Cita cca2b95e8c Merge pull request #143 from cita-777/Oauth-Management 
fix: improve oauth fallback handling for Gemini and Antigravity
 2026-03-17 23:16:21 +08:00
ciat-777 f565d1b54d fix: improve oauth error and model discovery fallbacks 2026-03-17 23:13:11 +08:00
Cita 2f2c93477d Merge pull request #141 from cita-777/Oauth-Management 
feat: expand gemini proxy compatibility matrix
 2026-03-17 21:30:41 +08:00
ciat-777 2e34f9033d feat: expand gemini proxy compatibility matrix 2026-03-17 21:22:23 +08:00
ciat-777 07351b527f feat: enhance OAuthManagement with improved provider handling and user feedback 2026-03-17 20:17:04 +08:00
Cita eb0c5475ca Merge pull request #140 from cita-777/feat/oauth-loopback-bridge 
fix: preserve codex workspaces and clarify oauth guidance
 2026-03-17 19:11:36 +08:00
Cita 4b155cbf33 Merge pull request #137 from weijiafu14/fix/gemini-strip-unknown-request-fields 
fix: use allowlist for Gemini native request fields to prevent 400 on unknown fields
 2026-03-17 19:09:11 +08:00
ciat-777 965ded8960 fix: preserve codex workspaces and clarify oauth guidance 2026-03-17 19:03:36 +08:00
Cita ddfa115eeb Merge pull request #135 from weijiafu14/fix/gemini-thought-signature-tool-calls 
fix: inject thoughtSignature into functionCall parts for OpenAI→Gemini conversion
 2026-03-17 18:37:12 +08:00
Cita 49f2adf470 Merge pull request #139 from cita-777/feat/oauth-loopback-bridge 
feat: align oauth loopback flow with cliproxyapi
 2026-03-17 18:02:31 +08:00
ciat-777 ebae2846b2 feat: align oauth loopback flow with cliproxyapi 2026-03-17 17:56:30 +08:00
Cita 5ee69a1ec5 Merge pull request #138 from cita-777/fix/sqlite-sites-unique-migration 
fix: recover site unique index bootstrap
 2026-03-17 17:47:31 +08:00
ciat-777 1021e6f234 fix: recover site unique index bootstrap 2026-03-17 17:42:18 +08:00
ciat-777 35f5bd3464 chore: align oauth defaults with cliproxyapi 2026-03-17 17:09:38 +08:00
weijiafu14 1bf2e46dd8 fix: use allowlist for Gemini native request fields to prevent 400 
Fixes #130

The inbound normalizer forwarded all unknown top-level fields to Gemini
API. Client-specific fields like requestId caused upstream 400 errors.

Changed from blocklist (only 3 entries) to allowlist of known Gemini API
fields: contents, systemInstruction, cachedContent, safetySettings,
generationConfig, tools, toolConfig, labels, model.
 2026-03-17 16:24:30 +08:00
weijiafu14 d20417d708 test: add 5 tests for thoughtSignature injection in OpenAI→Gemini path 2026-03-17 16:14:09 +08:00
weijiafu14 8bfdbda251 fix: inject thoughtSignature into functionCall parts for OpenAI→Gemini conversion 
When requests arrive via OpenAI-compatible endpoints and are converted to
Gemini format, functionCall parts were missing thoughtSignature. Gemini 3+
rejects such requests with 400 when thinking mode is enabled.

Changes:
- Extract thoughtSignature from tool_calls provider_specific_fields
- Inject into corresponding functionCall parts
- Fall back to dummy sentinel when thinking is enabled but no signature available
- Split signed/unsigned parts into separate model messages (Gemini requirement)

All existing tests pass (59/59).
 2026-03-17 16:08:08 +08:00
Cita 4c90028559 Merge pull request #133 from cita-777/feat/oauth-multi-provider 
feat: add multi-provider OAuth support for Claude and Gemini CLI
 2026-03-17 13:40:38 +08:00
ciat-777 d8e44eb805 feat: add multi-provider OAuth support for Claude and Gemini CLI 2026-03-17 13:36:44 +08:00
Cita 4e3dc92083 Merge pull request #129 from cita-777/feature/oauth-codex-management 
feat: implement Codex OAuth flow with loopback callback server and ma…
 2026-03-17 12:01:53 +08:00
ciat-777 575a15232b feat: implement Codex OAuth flow with loopback callback server and management UI 
- Add localCallbackServer for handling OAuth callback requests.
- Implement service functions for managing OAuth sessions and accounts.
- Create CodexAdapter for platform-specific interactions.
- Develop OAuthManagement page for managing OAuth connections and providers.
- Add tests for localCallbackServer and OAuthManagement components.
 2026-03-17 11:07:25 +08:00
Cita c156e0c164 Merge pull request #126 from cita-777/codex/masked-placeholder-tokens 
feat: add masked token placeholders and desktop icons
 2026-03-16 22:14:30 +08:00
cita 5f26ad976a feat: Implement Drizzle SQLite migration utility with schema verification and error recovery mechanisms. 2026-03-16 22:11:13 +08:00
cita 0a06f15e13 feat: add masked token placeholders and desktop icons 2026-03-16 21:36:23 +08:00
Cita 2409d9f184 Merge pull request #124 from cita-777/codex/zero-channel-routes 
[codex] add zero-channel placeholders and remaining workspace changes
 2026-03-16 19:40:46 +08:00
cita f67d871035 fix gemini stream payload typing 2026-03-16 19:38:17 +08:00
cita bec0457a92 include remaining workspace changes 2026-03-16 19:29:26 +08:00
cita 52441f2634 add zero-channel route placeholders 2026-03-16 19:25:02 +08:00
Cita 83c6b3460a Merge pull request #121 from cita-777/fix/release-packaging-and-model-dedupe 
Fix release packaging and model dedupe
 2026-03-16 16:40:24 +08:00
ciat-777 71dde80744 Fix release artifact name containing illegal slash from branch name 
The upload-artifact step used github.ref_name which includes forward
slashes for branch-triggered workflow_dispatch runs. Replace with
github.run_id which is always a safe integer.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
 2026-03-16 16:24:29 +08:00
ciat-777 b0e16fd3ea Fix model refresh dedupe and desktop packaging 2026-03-16 15:49:15 +08:00
Cita 60df68b712 Merge pull request #120 from cita-777/downstream-keys-ui-harmonize 
Refine DownstreamKeys page and unify site badge links
 2026-03-16 14:54:34 +08:00
ciat-777 d9e33e71ed Unify site badge links across console pages 2026-03-16 14:48:46 +08:00
ciat-777 bfb7ea180f Refine DownstreamKeys management page 2026-03-16 14:41:29 +08:00
ciat-777 7e7add1343 docs: add downstream key ui and site link plan 2026-03-16 13:32:56 +08:00
Hureru f36e867e1d test(proxy): add tests for account-level proxy resolution 
Cover getProxyUrlFromExtraConfig, resolveChannelProxyUrl,
withSiteRecordProxyRequestInit third parameter, and
withAccountProxyOverride ALS context propagation.
 2026-03-16 01:07:14 +08:00
Hureru f7b163c8b0 feat(web): add proxy URL field to account edit panel 
Add proxyUrl input to the account edit form with a hint about
supported protocols. Display a proxy badge on accounts that have
a custom proxy configured in both mobile and desktop list views.
 2026-03-16 01:06:57 +08:00
Hureru ffc2ad039c feat(proxy): wrap platform adapter calls with account proxy override 
Use withAccountProxyOverride to propagate account-level proxy URL
through AsyncLocalStorage for checkin, balance refresh, model
discovery, token sync, rebind-session verify, and token CRUD
operations. Also accept proxyUrl field in PUT /api/accounts/:id
with validation via parseSiteProxyUrlInput.
 2026-03-16 01:06:40 +08:00
Hureru 6d2f1c4b81 feat(proxy): pass account proxy through all proxy route handlers 
Thread account-level proxyUrl from extraConfig into
resolveChannelProxyUrl for endpointFlow and the third parameter
of withSiteRecordProxyRequestInit for direct fetch calls across
chat, responses, completions, embeddings, images, search, and
videos proxy routes.
 2026-03-16 01:06:16 +08:00
Hureru b43a4fd2ea fix(proxy): use proxyUrl parameter in endpointFlow fetch 
The ExecuteEndpointFlowInput.proxyUrl field was defined but ignored
by the fetch call. Apply it via withExplicitProxyRequestInit when
present, falling back to withSiteProxyRequestInit otherwise.
 2026-03-16 01:05:43 +08:00
Hureru 5687e87308 feat(proxy): add account-level proxy resolution core 
Add getProxyUrlFromExtraConfig to extract proxy URL from account
extraConfig JSON. Extend siteProxy with AsyncLocalStorage-based
withAccountProxyOverride, resolveChannelProxyUrl, and optional
accountProxyUrl parameter on withSiteRecordProxyRequestInit.

Priority chain: account proxyUrl > site useSystemProxy > direct.
 2026-03-16 01:03:32 +08:00
Cita e80fab5010 Merge pull request #114 from cita-777/fix/gemini-native-route-regressions 
fix: address gemini native and route coverage regressions
 2026-03-15 23:19:44 +08:00
ciat-777 bb608a39e9 fix: remove duplicate proxy log compat helper after rebase 2026-03-15 23:17:11 +08:00
ciat-777 4660c8ae0b fix: add downstream API key metadata and update proxy logs schema 
# Conflicts:
#	src/server/db/generated/mysql.upgrade.sql
#	src/server/db/generated/postgres.upgrade.sql
#	src/server/db/index.ts
 2026-03-15 23:14:44 +08:00
ciat-777 b15da138d1 feat: enhance MySQL upgrade generation with index prefix length control 
- Added support for specifying prefix lengths for live text-backed columns in MySQL upgrade SQL generation.
- Introduced `mysqlIndexPrefixRequirements` option to `generateUpgradeSql` function.
- Updated tests to validate the new functionality for MySQL upgrade generation.
- Removed legacy shared index compatibility specifications to avoid duplication with runtime schema bootstrap.
- Improved error handling and response structure in account token coverage refresh logic.
- Added tests for coverage refresh failure scenarios to ensure proper handling of token persistence.

# Conflicts:
#	src/server/db/sharedIndexSchemaCompatibility.test.ts
#	src/server/db/sharedIndexSchemaCompatibility.ts
#	src/server/index.ts
 2026-03-15 23:13:37 +08:00
ciat-777 1a2268cedb fix: update documentation to clarify default admin token for desktop installer on first launch 2026-03-15 23:08:49 +08:00
ciat-777 6ca08c1052 fix: update desktop server configuration for consistent port handling and access 2026-03-15 23:08:49 +08:00
ciat-777 4b42751953 fix: address gemini native and route coverage regressions 2026-03-15 23:08:49 +08:00
Delicious a64a51aa0c feat: 下游 API 密钥管理 (#103) 
* feat: downstream API key usage + proxy log attribution

* chore(schema): regenerate generated artifacts

* test: keep migration replay + platform detection tests stable

* feat: complete downstream api key management validation

* refactor: move downstream keys into console nav

* feat: upgrade downstream keys management console

* feat: harden downstream key management flows

* test: cover downstream key policy guards

* feat: add downstream key grouping and tags

* feat: polish downstream key search and log metadata

* test: fix sqlite migration bootstrap coverage

* perf: isolate vchart bundle loading

* fix: align downstream key drawer metrics

---------

Co-authored-by: DeliciousBuding <DeliciousBuding@users.noreply.github.com>
 2026-03-15 22:00:02 +08:00
dependabot[bot] 251348f784 build(deps-dev): bump wait-on from 8.0.5 to 9.0.4 (#109) 
Bumps [wait-on](https://github.com/jeffbski/wait-on) from 8.0.5 to 9.0.4.
- [Release notes](https://github.com/jeffbski/wait-on/releases)
- [Commits](https://github.com/jeffbski/wait-on/compare/v8.0.5...v9.0.4)

---
updated-dependencies:
- dependency-name: wait-on
  dependency-version: 9.0.4
  dependency-type: direct:development
  update-type: version-update:semver-major
...

Signed-off-by: dependabot[bot] <support@github.com>
Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com>
 2026-03-15 19:41:45 +08:00
dependabot[bot] 03363b27b1 build(deps-dev): bump electron from 35.7.5 to 41.0.2 (#110) 
Bumps [electron](https://github.com/electron/electron) from 35.7.5 to 41.0.2.
- [Release notes](https://github.com/electron/electron/releases)
- [Commits](https://github.com/electron/electron/compare/v35.7.5...v41.0.2)

---
updated-dependencies:
- dependency-name: electron
  dependency-version: 41.0.2
  dependency-type: direct:development
  update-type: version-update:semver-major
...

Signed-off-by: dependabot[bot] <support@github.com>
Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com>
 2026-03-15 19:41:35 +08:00
Cita 6237eb631f fix(db): tolerate runtime schema drift on startup (#113) 2026-03-15 19:07:46 +08:00
Cita cb405e785d Merge pull request #112 from cita-777/fix/external-db-runtime-upgrade 
fix: harden external database runtime upgrades
 2026-03-15 18:46:23 +08:00
ciat-777 b8735ad8c7 fix(db): enforce runtime external schema upgrades 2026-03-15 18:45:30 +08:00
Cita 67ad62c0d5 security: throttle sensitive admin routes (#111) 2026-03-15 17:28:34 +08:00
Cita 20480c4964 ci: add codeql scanning workflow (#108) 2026-03-15 16:55:04 +08:00
dependabot[bot] cc04466cad build(deps): bump undici from 6.24.0 to 6.24.1 in the runtime-http group (#107) 
Bumps the runtime-http group with 1 update: [undici](https://github.com/nodejs/undici).


Updates `undici` from 6.24.0 to 6.24.1
- [Release notes](https://github.com/nodejs/undici/releases)
- [Commits](https://github.com/nodejs/undici/compare/v6.24.0...v6.24.1)

---
updated-dependencies:
- dependency-name: undici
  dependency-version: 6.24.1
  dependency-type: direct:production
  update-type: version-update:semver-patch
  dependency-group: runtime-http
...

Signed-off-by: dependabot[bot] <support@github.com>
Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com>
 2026-03-15 16:54:48 +08:00
Cita b812a2262a chore: tighten dependabot major update policy (#105) 2026-03-15 16:28:20 +08:00
dependabot[bot] 8812577da4 build(deps-dev): bump react-router-dom from 6.30.3 to 7.13.1 (#98) 
Bumps [react-router-dom](https://github.com/remix-run/react-router/tree/HEAD/packages/react-router-dom) from 6.30.3 to 7.13.1.
- [Release notes](https://github.com/remix-run/react-router/releases)
- [Changelog](https://github.com/remix-run/react-router/blob/main/packages/react-router-dom/CHANGELOG.md)
- [Commits](https://github.com/remix-run/react-router/commits/react-router-dom@7.13.1/packages/react-router-dom)

---
updated-dependencies:
- dependency-name: react-router-dom
  dependency-version: 7.13.1
  dependency-type: direct:development
  update-type: version-update:semver-major
...

Signed-off-by: dependabot[bot] <support@github.com>
Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com>
 2026-03-15 16:27:58 +08:00
dependabot[bot] 7d265ef62c build(deps): bump the github-actions group with 12 updates (#90) 
Bumps the github-actions group with 12 updates:

| Package | From | To |
| --- | --- | --- |
| [actions/checkout](https://github.com/actions/checkout) | `5` | `6` |
| [dorny/paths-filter](https://github.com/dorny/paths-filter) | `3` | `4` |
| [actions/setup-node](https://github.com/actions/setup-node) | `5` | `6` |
| [docker/setup-buildx-action](https://github.com/docker/setup-buildx-action) | `3` | `4` |
| [docker/login-action](https://github.com/docker/login-action) | `3` | `4` |
| [docker/metadata-action](https://github.com/docker/metadata-action) | `5` | `6` |
| [docker/build-push-action](https://github.com/docker/build-push-action) | `6` | `7` |
| [actions/upload-pages-artifact](https://github.com/actions/upload-pages-artifact) | `3` | `4` |
| [actions/labeler](https://github.com/actions/labeler) | `5` | `6` |
| [actions/upload-artifact](https://github.com/actions/upload-artifact) | `4` | `7` |
| [actions/cache](https://github.com/actions/cache) | `4` | `5` |
| [actions/download-artifact](https://github.com/actions/download-artifact) | `4` | `8` |


Updates `actions/checkout` from 5 to 6
- [Release notes](https://github.com/actions/checkout/releases)
- [Changelog](https://github.com/actions/checkout/blob/main/CHANGELOG.md)
- [Commits](https://github.com/actions/checkout/compare/v5...v6)

Updates `dorny/paths-filter` from 3 to 4
- [Release notes](https://github.com/dorny/paths-filter/releases)
- [Changelog](https://github.com/dorny/paths-filter/blob/master/CHANGELOG.md)
- [Commits](https://github.com/dorny/paths-filter/compare/v3...v4)

Updates `actions/setup-node` from 5 to 6
- [Release notes](https://github.com/actions/setup-node/releases)
- [Commits](https://github.com/actions/setup-node/compare/v5...v6)

Updates `docker/setup-buildx-action` from 3 to 4
- [Release notes](https://github.com/docker/setup-buildx-action/releases)
- [Commits](https://github.com/docker/setup-buildx-action/compare/v3...v4)

Updates `docker/login-action` from 3 to 4
- [Release notes](https://github.com/docker/login-action/releases)
- [Commits](https://github.com/docker/login-action/compare/v3...v4)

Updates `docker/metadata-action` from 5 to 6
- [Release notes](https://github.com/docker/metadata-action/releases)
- [Commits](https://github.com/docker/metadata-action/compare/v5...v6)

Updates `docker/build-push-action` from 6 to 7
- [Release notes](https://github.com/docker/build-push-action/releases)
- [Commits](https://github.com/docker/build-push-action/compare/v6...v7)

Updates `actions/upload-pages-artifact` from 3 to 4
- [Release notes](https://github.com/actions/upload-pages-artifact/releases)
- [Commits](https://github.com/actions/upload-pages-artifact/compare/v3...v4)

Updates `actions/labeler` from 5 to 6
- [Release notes](https://github.com/actions/labeler/releases)
- [Commits](https://github.com/actions/labeler/compare/v5...v6)

Updates `actions/upload-artifact` from 4 to 7
- [Release notes](https://github.com/actions/upload-artifact/releases)
- [Commits](https://github.com/actions/upload-artifact/compare/v4...v7)

Updates `actions/cache` from 4 to 5
- [Release notes](https://github.com/actions/cache/releases)
- [Changelog](https://github.com/actions/cache/blob/main/RELEASES.md)
- [Commits](https://github.com/actions/cache/compare/v4...v5)

Updates `actions/download-artifact` from 4 to 8
- [Release notes](https://github.com/actions/download-artifact/releases)
- [Commits](https://github.com/actions/download-artifact/compare/v4...v8)

---
updated-dependencies:
- dependency-name: actions/checkout
  dependency-version: '6'
  dependency-type: direct:production
  update-type: version-update:semver-major
  dependency-group: github-actions
- dependency-name: dorny/paths-filter
  dependency-version: '4'
  dependency-type: direct:production
  update-type: version-update:semver-major
  dependency-group: github-actions
- dependency-name: actions/setup-node
  dependency-version: '6'
  dependency-type: direct:production
  update-type: version-update:semver-major
  dependency-group: github-actions
- dependency-name: docker/setup-buildx-action
  dependency-version: '4'
  dependency-type: direct:production
  update-type: version-update:semver-major
  dependency-group: github-actions
- dependency-name: docker/login-action
  dependency-version: '4'
  dependency-type: direct:production
  update-type: version-update:semver-major
  dependency-group: github-actions
- dependency-name: docker/metadata-action
  dependency-version: '6'
  dependency-type: direct:production
  update-type: version-update:semver-major
  dependency-group: github-actions
- dependency-name: docker/build-push-action
  dependency-version: '7'
  dependency-type: direct:production
  update-type: version-update:semver-major
  dependency-group: github-actions
- dependency-name: actions/upload-pages-artifact
  dependency-version: '4'
  dependency-type: direct:production
  update-type: version-update:semver-major
  dependency-group: github-actions
- dependency-name: actions/labeler
  dependency-version: '6'
  dependency-type: direct:production
  update-type: version-update:semver-major
  dependency-group: github-actions
- dependency-name: actions/upload-artifact
  dependency-version: '7'
  dependency-type: direct:production
  update-type: version-update:semver-major
  dependency-group: github-actions
- dependency-name: actions/cache
  dependency-version: '5'
  dependency-type: direct:production
  update-type: version-update:semver-major
  dependency-group: github-actions
- dependency-name: actions/download-artifact
  dependency-version: '8'
  dependency-type: direct:production
  update-type: version-update:semver-major
  dependency-group: github-actions
...

Signed-off-by: dependabot[bot] <support@github.com>
Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com>
 2026-03-15 16:27:13 +08:00
dependabot[bot] f69463eae7 build(deps): bump node-cron from 3.0.3 to 4.2.1 (#92) 
Bumps [node-cron](https://github.com/merencia/node-cron) from 3.0.3 to 4.2.1.
- [Release notes](https://github.com/merencia/node-cron/releases)
- [Commits](https://github.com/merencia/node-cron/compare/v3.0.3...v4.2.1)

---
updated-dependencies:
- dependency-name: node-cron
  dependency-version: 4.2.1
  dependency-type: direct:production
  update-type: version-update:semver-major
...

Signed-off-by: dependabot[bot] <support@github.com>
Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com>
 2026-03-15 16:26:36 +08:00
dependabot[bot] 348f7cbbf5 build(deps): bump dotenv from 16.6.1 to 17.3.1 (#93) 
Bumps [dotenv](https://github.com/motdotla/dotenv) from 16.6.1 to 17.3.1.
- [Changelog](https://github.com/motdotla/dotenv/blob/master/CHANGELOG.md)
- [Commits](https://github.com/motdotla/dotenv/compare/v16.6.1...v17.3.1)

---
updated-dependencies:
- dependency-name: dotenv
  dependency-version: 17.3.1
  dependency-type: direct:production
  update-type: version-update:semver-major
...

Signed-off-by: dependabot[bot] <support@github.com>
Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com>
 2026-03-15 16:26:36 +08:00
Cita fadb268d3a Merge pull request #88 from DeliciousBuding/fix/normalize-upstream-v1 
fix(proxy): baseUrl 已含 /v1 时避免重复拼接
 2026-03-15 15:58:17 +08:00
DeliciousBuding a6e6be9460 fix(proxy): normalize upstream url join 2026-03-15 15:54:48 +08:00
Cita f2dca9c871 Merge pull request #100 from cita-777/chore/dependabot-policy 
chore: tighten dependabot grouping and node baseline
 2026-03-15 15:50:22 +08:00
ciat-777 cad1bf6764 chore: tighten dependabot grouping and node baseline 2026-03-15 15:49:57 +08:00
Cita e94af6788b Merge pull request #89 from cita-777/dependabot/docker/docker/docker-0e8fc498de 
build(deps): bump node from 20-bookworm-slim to 25-bookworm-slim in /docker in the docker group
 2026-03-15 15:35:09 +08:00
dependabot[bot] 2e0e10ba9b build(deps): bump node in /docker in the docker group 
Bumps the docker group in /docker with 1 update: node.


Updates `node` from 20-bookworm-slim to 25-bookworm-slim

---
updated-dependencies:
- dependency-name: node
  dependency-version: 25-bookworm-slim
  dependency-type: direct:production
  dependency-group: docker
...

Signed-off-by: dependabot[bot] <support@github.com>
 2026-03-15 07:30:18 +00:00
Cita a228a1fbc4 Merge pull request #86 from cita-777/ci-parity-speedup 
ci: speed up PR checks and isolate schema parity
 2026-03-15 15:29:33 +08:00
ciat-777 f78cf434a9 fix(db): handle mysql information schema field casing 2026-03-15 15:27:09 +08:00
ciat-777 32789947b5 ci: document non-blocking audit policy 2026-03-15 15:21:48 +08:00
ciat-777 2699882569 fix(db): avoid mysql prefixes on non-text indexes 2026-03-15 15:16:15 +08:00
DeliciousBuding ef90169cc9 fix(proxy): avoid duplicated /v1 when joining upstream url 2026-03-15 15:13:50 +08:00
ciat-777 ef5f67e604 ci: parallelize PR checks and gate schema parity 2026-03-15 15:10:51 +08:00
ciat-777 982c0da010 docs: update security policy with detailed reporting guidelines and security considerations 2026-03-15 14:17:47 +08:00
ciat-777 916b9d6d73 feat: update issue templates for bug reports, documentation updates, feature requests, and questions with improved clarity and bilingual support 2026-03-15 14:00:23 +08:00
ciat-777 8cd81ff48d feat: enhance PR label backfilling with size validation and warning tracking 2026-03-15 13:39:19 +08:00
ciat-777 84fffaa6fc fix: upgrade github-script action to v8 in workflows 2026-03-15 13:33:35 +08:00
ciat-777 7f20fd920d Merge branch 'main' of https://github.com/cita-777/metapi 2026-03-15 13:30:58 +08:00
ciat-777 723fee99bf feat: add issue templates for bug reports, documentation updates, feature requests, and questions 2026-03-15 13:30:55 +08:00
Cita bf01ae335b Merge pull request #83 from ksmaze/test-gemini 
fix: remove gemini unrecognized fields before sending request
 2026-03-15 13:27:10 +08:00
Cita 4b80807e56 Merge pull request #85 from cita-777/fix/render-generated-assets 
fix: make external db bootstrap idempotent
 2026-03-15 13:17:41 +08:00
ciat-777 c9d4a10f15 fix(db): make external bootstrap idempotent 2026-03-15 13:16:50 +08:00
ksmaze 9e4ffbd6c8 address comment 2026-03-14 22:05:12 -07:00
Cita 4aff5e6e27 Merge pull request #84 from cita-777/fix/render-generated-assets 
fix(db): map mysql text primary keys to varchar
 2026-03-15 12:55:35 +08:00
ciat-777 69e282cce1 fix(db): map mysql text primary keys to varchar 2026-03-15 12:50:10 +08:00
ksmaze e227fc0dd3 fix: remove gemini unrecognized fields before sending request 2026-03-14 21:40:39 -07:00
Cita 5c8d0583b7 Merge pull request #80 from ksmaze/main 
feat: Add manual model availability management, including database sc…
 2026-03-15 12:18:05 +08:00
ksmaze 0c7e600d41 address comments 2026-03-14 20:34:02 -07:00
ksmaze ed3de8cca6 address comments 2026-03-14 20:21:17 -07:00
ksmaze 083ae0e720 address comments 2026-03-14 19:43:46 -07:00
ksmaze de22fc35fa feat: Add manual model availability management, including database schema updates, new API routes, and UI components. 2026-03-14 19:26:13 -07:00
Cita 5da3fbf874 Merge pull request #79 from cita-777/fix/render-generated-assets 
fix(build): copy runtime db generated assets
 2026-03-15 01:36:02 +08:00
ciat-777 7180cbf913 fix(build): copy runtime db generated assets 2026-03-15 01:21:17 +08:00
Cita e385d87502 Merge pull request #78 from cita-777/yolo-copilot 
test(db): yolo copilot retry for database parity
 2026-03-15 01:14:03 +08:00
ciat-777 30d54c34ff refactor(db): fence legacy runtime schema compat 2026-03-15 01:12:39 +08:00
ciat-777 7f88009356 test(db): verify upgrade paths against the schema contract 2026-03-15 01:12:39 +08:00
ciat-777 d562ea124f test(db): add live schema parity checks for sqlite mysql and postgres 2026-03-15 01:12:39 +08:00
ciat-777 81578e7f75 feat(db): generate schema artifacts and align sqlite baseline 2026-03-15 01:12:39 +08:00
ciat-777 590f34af93 feat(db): generate canonical schema contract from sqlite migrations 2026-03-15 01:12:39 +08:00
ciat-777 908b5195b2 test(db): isolate default sqlite path under vitest 2026-03-15 01:12:39 +08:00
ciat-777 064af9e0bb Revert "Merge pull request #77 from cita-777/database-parity" 
This reverts commit d2210b8ffb, reversing
changes made to b834a9bef8.
 2026-03-15 01:11:48 +08:00
Cita d2210b8ffb Merge pull request #77 from cita-777/database-parity 
refactor(db): database parity and runtime schema fencing
 2026-03-15 01:05:06 +08:00
ciat-777 cc675d51d5 refactor(db): fence legacy runtime schema compat 2026-03-14 23:56:04 +08:00
ciat-777 627b04d456 test(db): verify upgrade paths against the schema contract 2026-03-14 23:37:25 +08:00
ciat-777 af6bd86e23 test(db): add live schema parity checks for sqlite mysql and postgres 2026-03-14 23:27:28 +08:00
ciat-777 6d389cb3af feat(db): generate schema artifacts and align sqlite baseline 2026-03-14 23:04:33 +08:00
ciat-777 5bc5fb7039 feat(db): generate canonical schema contract from sqlite migrations 2026-03-14 22:45:05 +08:00
ciat-777 c037ea866e test(db): isolate default sqlite path under vitest 2026-03-14 22:42:22 +08:00
ciat-777 b834a9bef8 feat: add site_disabled_models and proxy tasks to database schema 
- Implemented site_disabled_models table with necessary SQL commands for SQLite, MySQL, and PostgreSQL.
- Updated ensureSiteSchemaCompatibility to create site_disabled_models if it doesn't exist.
- Enhanced database migration service to include site_disabled_models, proxy_video_tasks, and proxy_files in migration statements.
- Created shared index compatibility for new tables and ensured existing indexes are maintained.
- Added tests for schema parity to ensure consistency between runtime schema and defined schema.
 2026-03-14 21:16:43 +08:00
ciat-777 0c109278b9 feat(migrate): implement recovery for duplicate-column migrations and enhance migration handling 2026-03-14 20:40:46 +08:00
ciat-777 7d431d3ccd fix(db): detect duplicate-column from nested migration error cause 2026-03-14 19:25:55 +08:00
ciat-777 7bdcf27c41 merge: reconcile migrate bootstrap with duplicate-column recovery 2026-03-14 19:12:23 +08:00
ciat-777 7b8ce3dd13 feat: add recovery for duplicate-column migration errors and enhance migration utilities 2026-03-14 19:10:18 +08:00
Cita b3d678f738 Merge pull request #68 from grassroadsZ/feature/site-model-disable 
feat: 将模型禁用功能从站点移至连接管理
 2026-03-14 17:26:57 +08:00
ciat-777 595073cf4c fix(pr-68): harden model disable flows 
Co-authored-by: grassroadsZ <44087648+grassroadsZ@users.noreply.github.com>
 2026-03-14 17:22:06 +08:00
ciat-777 7bd48a3c6f fix: improve tester timeouts and telegram proxy config 2026-03-14 16:18:43 +08:00
ciat-777 201a806e51 fix(ci): resolve audit failure and update actions 2026-03-14 13:52:58 +08:00
ciat-777 1a1f0452b3 feat: add delete confirmation modal and enhance token handling 
- Implemented a DeleteConfirmModal component for confirming deletions across various pages (Accounts, Sites, Tokens).
- Updated Accounts and Sites pages to utilize the new modal for single and batch deletions.
- Enhanced TokensPanel to support group selection and improved token deletion handling with confirmation.
- Added functionality to skip confirmation for batch actions and handle token group fetching with error management.
- Improved error handling for expired sessions in NewApiAdapter and OneApiAdapter.
- Added tests for new delete confirmation behavior and token editing interactions.
 2026-03-14 13:31:15 +08:00
silent 0d44d3ba10 feat: 将模型禁用功能从站点管理移至连接管理 
- 在连接管理页面为每个账号添加独立的模型管理弹窗
- 弹窗内支持查看可用模型，进行「刷新模型」「全选」「全部禁用」「反选」等快捷操作
- 保存模型禁用配置后，系统会自动在后台触发并重建路由（rebuildRoutes），确保配置立即生效
- 从原站点编辑界面移除过时的禁用功能板块
- 修复因执行自动同步逻辑导致的 SQLite Drizzle Migration `duplicate column token_group` 报错，更新 bootstrap markers 及测试用例
 2026-03-14 12:07:27 +08:00
Cita ad791d87bb Merge pull request #64 from ShicYang/main 
feat: 使用日志新增自动刷新功能
 2026-03-13 23:38:03 +08:00
scyang 0e36d1c351 fix：错误文本添加换行，避免过长溢出 2026-03-13 12:50:43 +08:00
scyang 464b0be704 feat: 使用日志新增自动刷新功能 2026-03-13 12:49:51 +08:00
Cita faea80c4f9 Merge pull request #63 from ShicYang/main 
feat: 签到记录新增日期筛选
 2026-03-13 10:22:35 +08:00
scyang e861f8a48f feat: 签到记录新增日期筛选 2026-03-12 23:53:48 +08:00
Cita 14a174e0c7 Merge pull request #59 from bnvnvnv/feat/round-robin-routing-ui-polish 
feat: polish routing UI and add site header/log cleanup tooling
 2026-03-12 16:28:50 +08:00
ciat-777 89f7cddb93 style: format CSS keyframes for improved readability 2026-03-12 16:28:00 +08:00
ciat-777 701cd98f73 feat: enhance site observability panel with improved latency color gradients and new UI components 2026-03-12 16:26:06 +08:00
bnvnvnv b6da71b1d6 feat: add site headers editor and scheduled log cleanup 2026-03-12 08:12:29 +00:00
bnvnvnv 1da3608d42 fix: address review feedback for models and routing 2026-03-12 05:51:53 +00:00
Cita e6babf6cfd Merge pull request #58 from bnvnvnv/feat/round-robin-routing-ui-polish 
feat: round-robin routing + cooldown; fix models marketplace site filter; clarify token binding UX
 2026-03-12 13:39:14 +08:00
bnvnvnv 5a7531f635 feat: add round robin routing and improve token binding UX 2026-03-12 05:18:36 +00:00
Cita cb93b28c71 Merge pull request #56 from Hureru/fix/mysql-migration-text-index-error 
fix(db): resolve MySQL migration error with TEXT column UNIQUE index
 2026-03-12 00:12:16 +08:00
Hureru af83d3525b fix(db): change model_name from TEXT to VARCHAR(191) for MySQL UNIQUE index compatibility 2026-03-11 23:50:02 +08:00
Cita d7c9e98fa7 Merge pull request #54 from bnvnvnv/feat/site-observability-proxy-logs 
feat: add site observability drilldown for proxy logs
 2026-03-11 21:43:20 +08:00
bnvnvnv a5121b8f9f fix: address observability review feedback 2026-03-11 12:00:35 +00:00
root ce32744bad Merge remote-tracking branch 'upstream/main' into feat/site-observability-proxy-logs 2026-03-11 11:44:29 +00:00
bnvnvnv bc3c731ed2 feat: add site observability log drilldown 2026-03-11 11:03:57 +00:00
Cita f904700b73 Merge pull request #53 from Hureru/refactor/token-routes-page 
refactor: 重构 TokenRoutes 页面，支持分层加载、网格布局和性能优化
 2026-03-11 16:14:25 +08:00
cita b35e9fcc7a docs: add live demo section to README files 2026-03-11 16:05:38 +08:00
Hureru f5fcf5d707 fix: address code review findings 
- fix(api): use effectiveTokenId in route channel insert to match duplicate detection logic
- fix(css): rename keyframes to kebab-case (filter-bar-slide-down/up)
- fix(web): wrap "保存中..." text with tr() in ManualRoutePanel
- fix(web): use ref for fresh cache check and add error handling in useRouteChannels
 2026-03-11 15:51:10 +08:00
Hureru 8128d6e036 fix(web): remove outdated decision auto-skip hint from info tip 2026-03-11 14:58:33 +08:00
cita 921c551a3a feat: Implement default API site seeding, add a dialect-aware setting upsert utility, and introduce check-in API routes with background task processing. 2026-03-11 14:31:23 +08:00
Hureru a0e474c561 perf(web): optimize TokenRoutes rendering and add infinite scroll 
Rendering optimization:
- Extract stable routePatterns derived value to avoid expensive useMemo
  recomputation on enable/disable toggle (only recompute when patterns change)
- Stabilize all RouteCard callback props with useCallback+useRef pattern
- Pre-compute missingTokenSiteItems as useMemo index instead of per-render call
- Add EMPTY_MISSING_ITEMS constant for stable empty array reference

Infinite scroll:
- Replace manual "load more" button with IntersectionObserver sentinel
- Auto-load next chunk when scrolling within 200px of bottom
 2026-03-11 14:06:23 +08:00
Hureru 47064ba7af perf(web): cache matchesModelPattern regex compilation and results 
- Cache compiled glob RegExp objects to avoid repeated new RegExp()
- Cache model+pattern match results (up to 4000 entries)
- Significantly reduces CPU cost of pattern matching in route computations
 2026-03-11 14:05:00 +08:00
Hureru 49dbaf3c6a fix(web): fix route card title overflow and optimize with React.memo 
Layout fixes:
- Title uses flex:1 + text-overflow:ellipsis, badges always right-aligned
- Enable button has minWidth for cross-card vertical alignment
- Icon and badges use flexShrink:0 to prevent compression

Performance:
- Wrap RouteCard with React.memo to skip re-renders for unchanged routes
- Change callback props to accept routeId for stable reference compatibility
 2026-03-11 14:04:04 +08:00
Hureru 69cc491d3a fix(web): fix AddChannelModal checkbox toggle and click area 
- Move onClick handler to outer card div for full-area click support
- Set checkbox to readOnly with pointerEvents:none to prevent double-toggle
- Add stopPropagation on token select section to avoid unintended toggling
 2026-03-11 14:01:45 +08:00
cita f43247e91d feat: add multi-dialect database schema compatibility logic for proxy files. 2026-03-11 13:51:13 +08:00
cita 2773b835a9 feat: set PORT environment variable to 4000 2026-03-11 13:40:02 +08:00
cita c640b36c96 feat: add deployment documentation and disable automatic PORT value generation in render.yaml 2026-03-11 13:37:31 +08:00
cita 742581efaa feat: Add Render deployment configuration and documentation, including a deploy button in README. 2026-03-11 13:21:19 +08:00
Hureru 90f92711fd fix(web): wire AddChannelModal with missing token hints and channel context 
Pass missingTokenHints, onCreateTokenForMissing, and
existingChannelAccountIds to AddChannelModal so users can see
accounts that need token creation and identify already-added channels.
 2026-03-11 12:00:07 +08:00
Hureru d2e1e7765d fix(web): add missing token hints and existing channel badge to AddChannelModal 
- Display accounts that have model availability but lack tokens,
  with a "create token" action button for each
- Mark already-added channel accounts with a badge
- Improve empty state message to guide users on next steps
- Search now filters both available accounts and missing-token accounts
 2026-03-11 11:53:26 +08:00
Hureru 5c026df760 fix(db): add schema compatibility for account_tokens.token_group column 
Existing databases created before the token_group column was added would
fail on data import. Add accountTokenSchemaCompatibility module to
ALTER TABLE add the missing column, following the established pattern.
 2026-03-11 01:15:11 +08:00
Hureru 457b4915da test: update TokenRoutes tests for summary-based data loading 
Adapt all 3 test files to mock getRoutesSummary instead of getRoutes,
use summary-format data structures, and expand cards before asserting
channel-level content.
 2026-03-11 01:15:02 +08:00
Hureru 1183d7fde0 refactor(web): rewrite TokenRoutes with grid layout and layered loading 
Replace full-data loading with summary-first approach. Implement CSS Grid
multi-column card layout, collapsible filter panel, and collapsed-by-default
route cards that load channels on demand when expanded.
 2026-03-11 01:14:52 +08:00
Hureru fa232950b9 refactor(web): extract TokenRoutes into modular sub-components 
Split the 2447-line TokenRoutes.tsx into focused modules:
- types.ts: shared type definitions
- utils.ts: pure helper functions
- SortableChannelRow.tsx: DnD channel row component
- ManualRoutePanel.tsx: route create/edit form
- RouteFilterBar.tsx: collapsible filter panel with chip layout
- RouteCard.tsx: collapsed/expanded route card
- AddChannelModal.tsx: batch add channel modal
- useRouteChannels.ts: on-demand channel loading hook
 2026-03-11 01:14:42 +08:00
Hureru bb7ea90f0b feat(api): add layered route loading endpoints 
Add GET /api/routes/summary for lightweight first-screen data,
GET /api/routes/:id/channels for on-demand channel loading,
and POST /api/routes/:id/channels/batch for bulk channel creation.
Extract fetchChannelsForRoutes() as reusable helper.
 2026-03-11 01:14:31 +08:00
Hureru 2343383729 feat: add lightweight /api/routes/lite endpoint for route selectors 
Avoid loading full route data (channels, decision snapshots) when Settings
page only needs basic route info for selectors.
 2026-03-10 23:06:56 +08:00
cita 5e14c2282f feat: Add MobileDrawer component and About page, and update package version. 2026-03-10 17:16:12 +08:00
cita 2268641759 Merge branch 'main' of https://github.com/cita-777/metapi 2026-03-10 16:59:43 +08:00
cita 521b5bf391 feat: Implement core web application with routing, user authentication, theme settings, user profiles, and mobile navigation. 2026-03-10 16:59:39 +08:00
Cita a60adf4e26 Merge pull request #50 from cita-777/codex/model-refresh-health 
Codex/model refresh health
 2026-03-10 16:55:47 +08:00
cita 747b985513 feat: refine model refresh toasts and failure handling 2026-03-10 16:44:10 +08:00
cita 803c01f308 Merge branch 'main' of https://github.com/cita-777/metapi 2026-03-10 16:38:26 +08:00
cita 15ea4db4d9 Refactor code structure for improved readability and maintainability 2026-03-10 16:38:21 +08:00
Cita 601f3bf407 Merge pull request #49 from cita-777/codex/mobile-responsive 
Codex/mobile responsive
 2026-03-10 16:29:52 +08:00
cita 01bf2212f8 fix: reset health on model discovery success 2026-03-10 16:27:10 +08:00
cita ab2220bc09 fix: export MobileDrawer 2026-03-10 16:25:44 +08:00
cita ab4033c1fa fix: avoid brandList TDZ in TokenRoutes 2026-03-10 16:18:44 +08:00
cita 1dbde9346a fix: guard useIsMobile in non-browser 2026-03-10 16:14:37 +08:00
cita d5cd8292eb test: cover model refresh early returns 2026-03-10 16:12:38 +08:00
cita 715a2dba9b feat: add mobile actions and CSS 2026-03-10 16:05:24 +08:00
cita e1b4452c82 feat: classify model refresh failures and update health 2026-03-10 16:02:45 +08:00
cita 3acba86edf test: expand model refresh failure contract 2026-03-10 15:55:33 +08:00
cita f01379f7a3 feat: convert logs and routes pages to mobile cards 2026-03-10 15:48:10 +08:00
cita 21cb2ddc62 test: cover model refresh failure health 2026-03-10 15:37:51 +08:00
cita b8ebf98b68 fix: add account mobile hints 2026-03-10 15:35:13 +08:00
cita 8a3ab0f625 docs: add model refresh health design 2026-03-10 15:28:57 +08:00
cita b23c5ece83 feat: convert core pages to mobile cards 2026-03-10 15:27:28 +08:00
cita 37e325d3cf feat: add mobile card components 2026-03-10 15:09:41 +08:00
cita d91a160455 feat: add mobile nav drawer 2026-03-10 15:00:43 +08:00
cita 2d8e1b9019 feat: add mobile drawer shell 2026-03-10 14:55:21 +08:00
cita ed830563d2 test: assert mobile layout attribute 2026-03-10 14:49:22 +08:00
cita 4e3d82aae1 feat: add mobile layout detection 2026-03-10 14:39:57 +08:00
cita dbf828467b chore: ignore local worktrees 2026-03-10 14:32:10 +08:00
cita 8ea7be68c1 Refactor code structure for improved readability and maintainability 2026-03-10 14:22:55 +08:00
cita 9a976232e2 feat: add validation for streaming requests on compact responses and include serialization mode in response 2026-03-10 13:01:47 +08:00
cita cd031b732f feat: enhance response serialization for compact mode 
- Added support for preserving native response.compaction payloads when compact serialization is requested in `serializeResponsesFinalPayload`.
- Implemented serialization of compact mode as `response.compaction` instead of an ordinary response object.
- Introduced a new type `ResponsesFinalSerializationMode` to manage serialization modes.
- Refactored `serializeResponsesFinalPayload` to handle different serialization modes and usage payloads.
- Added tests to ensure correct behavior for compact serialization and preservation of upstream payloads.
- Updated favicon assets and documentation configuration for VitePress.
 2026-03-10 01:28:34 +08:00
cita 74d2e559ec feat: add test for unchanged candidates when avoidSec is omitted and improve condition check in filterRecentlyFailedCandidates 2026-03-09 23:35:21 +08:00
cita 217dff0f72 fix: update test assertions to access parsed claudeOriginalBody structure 2026-03-09 23:25:53 +08:00
Cita fd7970e2ad Merge pull request #45 from cita-777/codex/docs-user-journey-rewrite 
feat: Implement compatibility strategies for responses and chat endpo…
 2026-03-09 22:48:56 +08:00
cita 0f8176cd04 feat: Implement compatibility strategies for responses and chat endpoints 
- Added `routeCompatibility.ts` to handle response compatibility for different endpoints.
- Introduced `chatEndpointStrategy.ts` to manage chat endpoint recovery and downgrading logic.
- Created tests for chat formats and input file handling in `chatFormatsCore.test.ts` and `inputFile.test.ts`.
- Developed `endpointCompatibility.ts` to define compatibility checks and header building for various endpoints.
- Implemented protocol lifecycle management in `protocolLifecycle.ts` and corresponding tests in `protocolModel.test.ts`.
- Enhanced tooltip functionality with a new `TooltipLayer` component and associated tests.
- Refactored existing components to improve tooltip handling and ensure proper rendering in the application.
 2026-03-09 22:48:10 +08:00
Cita 482d58cd88 Merge pull request #43 from cita-777/codex/docs-user-journey-rewrite 
feat: rewrite user journey documentation and enhance input file handl…
 2026-03-09 18:27:07 +08:00
cita 15d4b207cc feat: rewrite user journey documentation and enhance input file handling in responses 2026-03-09 18:25:09 +08:00
cita 3da1b93c39 feat: update input_file data format to include data URL scheme 2026-03-09 15:45:43 +08:00
cita 44799c0399 fix(tests): remove incorrect mime_type field from input_file in tests 2026-03-09 13:55:57 +08:00
cita e8cfe41e87 Merge branch 'main' of https://github.com/cita-777/metapi 2026-03-09 13:48:42 +08:00
cita 136a038538 feat(tests): enhance modelTesterSession tests and add proxy logs tests 
- Updated modelTesterSession tests to serialize assistant history as output_text and removed mime_type from input_file.
- Introduced new tests for stats proxy logs routes, covering paginated log retrieval and detailed log views with parsed billing details.
- Added server-driven tests for ProxyLogs component to validate API interactions and UI rendering based on server data.
 2026-03-09 13:48:39 +08:00
Cita 55b10111f1 Update star history chart link with version 2026-03-09 00:12:54 +08:00
Cita 0e76d2304d Clean up README by removing extra line 
Removed an empty line before the Star History section.
 2026-03-09 00:10:37 +08:00
cita 3dcf45851f Refactor reasoning handling and metadata management in responses 
- Updated chat stream tests to clarify reasoning behavior and ensure correct handling of include lists.
- Enhanced responses proxy route to normalize include lists and apply default reasoning includes based on request context.
- Improved transformer metadata handling, ensuring proper serialization and deserialization of metadata records.
- Added tests for preserving reasoning signatures and managing citations in OpenAI-compatible responses.
- Refined the logic for injecting default includes in responses and ensured compatibility with codex surface defaults.
 2026-03-08 23:03:33 +08:00
cita 7bd3114ea0 feat: implement proxy input file resolution and storage 
- Added `inputFiles.ts` for handling input file resolution, including validation and normalization of file types.
- Introduced `proxyFileStore.ts` for managing file storage, retrieval, and deletion with owner-based isolation.
- Created tests for proxy file storage functionality in `proxyFileStore.test.ts`.
- Developed `proxyInputFileResolver.ts` to resolve input files in OpenAI and response formats.
- Added utility functions for handling reasoning signatures in `reasoningTransport.ts` and corresponding tests.
- Enhanced shared input file transformers in `inputFile.ts` for better file handling and type inference.
 2026-03-08 22:10:31 +08:00
cita ede8998244 Add comprehensive tests for Anthropics and Gemini transformers 
- Implement tests for anthropicMessagesTransformer including serialization and event handling in stream.test.ts.
- Add usage extraction tests for anthropicMessagesUsage in usage.test.ts.
- Create extensive tests for Gemini generate content aggregation and outbound usage in aggregator-outbound-usage.test.ts.
- Introduce tests for Gemini stream handling and payload parsing in stream.test.ts.
- Enhance OpenAI response serialization tests to ensure proper mapping of usage details and preservation of annotations in outbound.test.ts.
 2026-03-08 16:42:41 +08:00
cita 7081be14c7 feat: Add route grouping schema compatibility checks and integration into migration process 2026-03-08 13:29:25 +08:00
cita 4172ad4297 feat: Implement useThemeLabelColor hook and update components to utilize it for label color management 2026-03-08 13:07:27 +08:00
cita 8e291b9bf8 feat: Enhance Gemini and chat proxy routes with improved error handling and fallback mechanisms 2026-03-08 12:54:24 +08:00
cita 23922a5965 feat: Add normalized types and utility functions for handling chat formats 
- Introduced `NormalizedContentBlock`, `NormalizedUsage`, and related types for structured data handling.
- Implemented utility functions for creating and merging normalized usage statistics.
- Added a new module for shared transformers to manage chat formats.

feat: Implement app local state management

- Created functions to clear application installation state and manage local storage keys.
- Added constants for theme and user profile storage keys.

test: Add tests for BrandIcon component rendering

- Implemented tests to ensure BrandIcon does not force a colored background for recognized brands.

test: Enhance ModelAnalysisPanel tests

- Added tests for rendering token summaries with compact units in ModelAnalysisPanel.

test: Add tests for ModernSelect component

- Implemented tests to verify icon rendering for selected options in ModernSelect.

test: Add number formatting tests

- Created tests for `formatCompactTokenMetric` to validate token formatting logic.

feat: Implement account creation intent handling

- Added logic to handle session and API key creation intents in the Accounts page.

test: Add tests for dashboard performance card

- Implemented tests to verify rendering of performance metrics in the dashboard.

feat: Implement default connection segment resolution

- Added logic to determine initial connection segments based on platform types.

test: Add tests for settings factory reset functionality

- Implemented tests to verify the factory reset process and local state clearing.

test: Add tests for site creation redirect logic

- Implemented tests to verify redirection based on site capabilities during creation.

test: Add tests for token routes refresh decision action

- Implemented tests to verify refresh decision actions in TokenRoutes.

test: Add tests for token routes snapshot load

- Implemented tests to verify loading of cached snapshot data in TokenRoutes.
 2026-03-08 12:08:57 +08:00
cita ed05b37626 feat: enhance TokenRoutes with edit functionality and route visibility management 
- Added editing capabilities for route management in TokenRoutes, allowing users to modify existing routes.
- Introduced a reset function for the route form to clear inputs after adding or editing routes.
- Implemented a visibility filter for routes, ensuring exact routes covered by group routes are hidden from the main list.
- Updated tests to cover new functionalities, including editing routes and verifying visibility logic.
- Created a new helper function to build a list of visible routes based on defined criteria.
- Enhanced schema compatibility checks for site configurations, ensuring necessary columns are added to the database.
 2026-03-07 19:56:40 +08:00
cita 5ad5b87b16 feat: add withSiteRecordProxyRequestInit mock to siteProxy for testing 2026-03-07 18:17:15 +08:00
cita c437d93715 Add tests for centered modal adoption, search modal results, and accounts batch actions 
- Implement tests for the CenteredModal component to ensure it follows the shared modal shell pattern.
- Add comprehensive tests for the SearchModal results, including API interactions and UI behavior.
- Create tests for accounts batch actions, verifying the functionality of refreshing balances and selecting accounts via row clicks.
- Introduce tests for the accounts centered modal to confirm the use of CenteredModal for add/edit/rebind flows.
- Add tests for the accounts edit panel to ensure proper rendering and functionality when opening the edit modal.
- Implement tests for the accounts tokens header to verify the reuse of the accounts page header in the tokens segment.
- Create tests for the system proxy settings, ensuring the correct saving of the proxy URL.
- Add tests for the tokens actions layout to confirm the proper layout and styling of token row actions.
- Implement tests for the tokens batch actions, including deletion of selected tokens and row selection behavior.
- Introduce tests for the tokens focus navigation to ensure the correct highlighting of focused token rows.
 2026-03-07 18:04:05 +08:00
cita c31bbcbb51 refactor: remove deprecated apiKey from site management and update related functionality 
- Removed apiKey from SiteRow type and related forms in Sites component.
- Updated site saving logic to handle site creation without apiKey.
- Adjusted tests to ensure apiKey is not included in site editor state.
- Refactored Tokens component to support embedded mode and redirect logic.
- Added migration tests for site apiKey to account migration service.
- Implemented siteApiKeyMigrationService to handle migration of apiKey to account tokens.
- Enhanced tests for segmented connections in Accounts and redirect logic for Tokens.
 2026-03-07 15:03:30 +08:00
cita a98a6f2c18 ci: update desktop packaging process and add smoke test for native modules on Windows 2026-03-07 11:40:57 +08:00
cita 98a2936416 refactor: improve SQLite migration handling and update .gitignore 2026-03-07 00:29:56 +08:00
Cita 1e12ec5211 Merge pull request #35 from cita-777/codex/run-release.yml-to-simulate-github-actions-ohq25x 
Normalize downloaded dist layout in release workflow, skip npmRebuild during packaging, bump version to 1.2.1
 2026-03-06 23:28:22 +08:00
Cita 87d772703f Merge branch 'main' into codex/run-release.yml-to-simulate-github-actions-ohq25x 2026-03-06 23:27:30 +08:00
Cita 200489539b chore: bump version to 1.2.1 2026-03-06 23:26:59 +08:00
Cita 95c7b5b10d Merge pull request #34 from cita-777/codex/run-release.yml-to-simulate-github-actions-8hwayv 
Normalize dist layout and disable npm rebuild in release workflow
 2026-03-06 23:07:26 +08:00
cita 3124b26bd0 Merge branch 'main' of https://github.com/cita-777/metapi 2026-03-06 22:45:00 +08:00
cita 0d99419b9f feat: implement GOB encoding support for user ID extraction and enhance cookie handling in NewApiAdapter 2026-03-06 22:44:56 +08:00
Cita 1263edbccf Merge branch 'main' into codex/run-release.yml-to-simulate-github-actions-8hwayv 2026-03-06 22:01:51 +08:00
Cita d668906c8e ci: normalize dist artifact before desktop packaging 2026-03-06 22:00:29 +08:00
Cita 81e61f96d8 Merge pull request #33 from cita-777/codex/run-release.yml-to-simulate-github-actions 
Disable npm rebuild during desktop packaging and remove AppImage prefetch step
 2026-03-06 21:43:27 +08:00
Cita 5e6e1ca245 ci: make release packaging locally reproducible 2026-03-06 21:36:23 +08:00
cita 02bf0393e6 feat: enhance desktop build process with artifact upload and download, and update server working directory resolution 2026-03-06 20:25:48 +08:00
cita 6c51801e50 feat: add macOS ad-hoc signing support 
- Implemented afterPack script to ensure ad-hoc signature for macOS builds.
- Created macosSignUtils module to handle app path retrieval, signature inspection, and ad-hoc signing.
- Added functions to check if the app is signed and apply ad-hoc signing if necessary.
 2026-03-06 19:58:38 +08:00
cita 19125d686e Merge branch 'main' of https://github.com/cita-777/metapi 2026-03-06 19:29:12 +08:00
cita 56b930495b feat: enhance release workflow with Electron cache restoration and retry logic for desktop builds 2026-03-06 19:29:10 +08:00
Cita 1c98db723e Merge pull request #32 from Zhou-Ruichen/fix/suppress-duplicated-reasoning-content 
fix(chatFormats): suppress content when it duplicates reasoning_content
 2026-03-06 18:41:48 +08:00
cita e88fc0a997 feat: implement proxy billing details handling and resolveProxyLogBilling function 2026-03-06 18:28:45 +08:00
Ruichen Zhou 83608c3521 fix(chatFormats): suppress content when it duplicates reasoning_content 
Some upstream providers (e.g. certain OpenAI-compatible aggregators)
emit thinking/reasoning tokens with the same text written to both
delta.content and delta.reasoning_content simultaneously.

When metapi forwarded these chunks as-is, downstream clients would read
delta.content and display the internal reasoning text to end users —
appearing as word-by-word "thinking narration" in chat interfaces.

Fix: after resolving both contentDelta and reasoningDelta, suppress
contentDelta when it is non-empty and identical to reasoningDelta.
This covers the duplicate-write pattern without affecting any legitimate
case (a provider would never intentionally set content == reasoning).
 2026-03-06 11:28:07 +01:00
cita 3748e6dcb6 feat: add proxy log billing details handling and schema management 2026-03-06 18:12:12 +08:00
cita bf216d7011 Merge branch 'main' of https://github.com/cita-777/metapi 2026-03-06 17:10:04 +08:00
cita 55b1ae564e feat: update error messages in NewApiAdapter tests to use correct Chinese translations 
feat: enhance proxy usage parser to include cache read and creation tokens

feat: add billing details to ProxyLog interface and implement related formatting functions

fix: correct mojibake issues in source files and add regression test for mojibake detection

chore: add SQL migration for billing details in proxy_logs table

test: improve site speed button tests to ensure proper state updates without DOM lookups
 2026-03-06 17:10:01 +08:00
Cita 4d9bd52c01 Update star history chart link format 2026-03-06 16:58:30 +08:00
cita 2a810facb8 feat: implement macOS notarization and ad-hoc signing in afterSign script 
feat: add run-server script to manage server execution and compatibility checks

feat: create main application logic for desktop with window management, server handling, and auto-updater

test: add unit tests for desktop runtime helpers

feat: implement desktop server environment configuration and health check

test: add tests for server configuration and desktop routes

feat: add native module guard for better-sqlite3 compatibility

test: add tests for native module guard functionality

test: add comprehensive tests for account verification feedback handling

feat: implement account verification feedback helpers

chore: add TypeScript configuration for desktop builds
 2026-03-06 16:24:41 +08:00
cita acdc846b13 Refactor logging timestamps to use formatUtcSqlDateTime function across proxy routes and services; add storedTimestampRepairService for fixing createdAt values in database 2026-03-06 11:57:30 +08:00
cita 7fda94f27d feat(models): update model selection logic and add comprehensive tests for /v1/models route 2026-03-05 21:52:35 +08:00
cita fdf4f30987 feat: add createdAt timestamps to check-in logs and improve i18n translations 
- Added createdAt timestamps to various check-in log entries in checkinService.ts for better tracking.
- Updated i18n translations in Models.tsx to improve user experience with accurate Chinese translations.
- Reduced default page size in ProgramLogs.tsx and ProxyLogs.tsx from 80 and 100 to 50 for better performance.
- Enhanced ProxyLogs.tsx with memoization for filtered logs and summary statistics.
- Implemented support for parsing Unix timestamps and PostgreSQL-style timezone offsets in checkinLogTime.ts.
- Added comprehensive tests for database proxy query wrapper in index.proxy-wrap.test.ts to ensure functionality.
 2026-03-05 21:18:49 +08:00
cita 0d5e56f478 feat(settings): add validation for SQLite connection strings and improve error messages 2026-03-05 19:37:09 +08:00
cita b122893796 Add tests for settings database runtime configuration API 
- Implement tests for retrieving and saving runtime database configuration.
- Validate handling of invalid configuration payloads.
- Utilize Fastify for API testing with Vitest.
- Ensure proper cleanup of database state between tests.
 2026-03-05 18:57:18 +08:00
cita 283c052fa5 test:Add database migration service with normalization and masking functions 
- Implemented `normalizeMigrationInput` to standardize database migration input for sqlite, mysql, and postgres.
- Added `maskConnectionString` to obscure sensitive credentials in connection strings.
- Created comprehensive tests for migration input normalization and connection string masking.
- Established database schema creation logic for multiple dialects (sqlite, mysql, postgres).
- Developed functions for managing database transactions, including begin, commit, and rollback.
- Implemented data insertion logic from backup snapshots into the target database.
 2026-03-05 17:38:52 +08:00
cita 0168592c95 Merge branch 'main' of https://github.com/cita-777/metapi 2026-03-05 14:28:12 +08:00
cita 4a61148b4f feat(accounts): extend rebind-session API to handle refresh token and expiration fields 2026-03-05 14:28:10 +08:00
Cita b6860df426 Update Star History chart image link in README 2026-03-05 13:25:17 +08:00
cita 27501b5a85 feat(ProgramLogs): add event status summary parsing and corresponding labels 2026-03-05 13:08:59 +08:00
cita 11fc61f4fa feat(donehub): add user self endpoint handling and balance calculation logic 2026-03-05 12:23:45 +08:00
cita 24769706e1 feat(proxy): enhance error handling for chat proxy requests with fallback logic 2026-03-04 22:12:02 +08:00
cita ecc117d7ee feat(proxy): update endpoint resolution order for 'anyrouter' platform 2026-03-04 21:48:26 +08:00
cita ebc5934547 feat(platforms): enhance platform detection by adding URL hinting logic 2026-03-04 21:05:30 +08:00
cita 9fbf434bd6 feat(proxy): enhance upstream endpoint handling and error summarization 
- Added new utility functions for building minimal JSON headers and normalizing responses for compatibility.
- Implemented detailed error handling for unsupported media types and endpoint downgrade scenarios.
- Introduced a new endpoint flow mechanism to manage retries and downgrades between different upstream endpoints.
- Enhanced tests for endpoint flow and error summarization to cover various edge cases and scenarios.
- Updated CSS styles for accounts table to improve layout and responsiveness.
- Refactored ModelTester component to handle incremental text updates more effectively.
 2026-03-04 20:59:48 +08:00
cita 82e9f3b601 Add tests for accounts login shield and proxy log retention service 
- Implement tests for accounts login shield detection, verifying behavior when login fails with HTML JSON parse syntax error.
- Create tests for proxy log retention service, ensuring expired logs are deleted based on retention days and that cleanup is skipped when retention is disabled.
- Add tests for token router cache, validating that route snapshots are maintained within TTL until explicitly invalidated.
- Introduce necessary mock setups and database seeding for comprehensive testing.
 2026-03-04 14:59:06 +08:00
cita 536d957a9e Merge branch 'main' of https://github.com/cita-777/metapi 2026-03-04 13:46:34 +08:00
cita e281e45e84 feat: add comprehensive tests for token candidates and proxy log path metadata 
- Implemented tests for the `/api/models/token-candidates` endpoint to verify model availability and token coverage scenarios.
- Added tests for `composeProxyLogMessage` to ensure proper formatting of log messages with downstream and upstream metadata.
- Created utility functions for parsing proxy log path metadata and handling missing token hints.
- Developed tests for the `Sites` and `TokenRoutes` components to validate UI behavior and interactions, including scrolling and group expansion.
- Introduced a custom hook `useAnimatedVisibility` for managing visibility animations in components.
- Enhanced the documentation link for site resources.
 2026-03-04 13:46:31 +08:00
Cita 4b77207d03 Update star history chart version in README 2026-03-03 18:50:28 +08:00
cita d49fcefa05 feat: 增强错误处理，添加对特定无效请求的处理逻辑 2026-03-03 17:29:37 +08:00
cita 9ff138f0b5 feat: 添加 Telegram 通知支持，更新配置和文档 2026-03-03 17:25:27 +08:00
ciat-777 cf6b2285fb feat: 更新文档，添加项目架构和界面预览部分 2026-03-03 15:13:52 +08:00
ciat-777 eff6f22f6d Add unit tests for backupService to validate import/export functionality 2026-03-03 14:50:59 +08:00
ciat-777 5cebc1554f feat: 增强聊天代理流行为，优化错误处理和工具调用逻辑 2026-03-03 00:03:34 +08:00
ciat-777 e2fce12e20 feat: 更新文档链接，增强客户端接入指南，优化代理日志记录和错误处理 2026-03-02 23:43:29 +08:00
ciat-777 fed7ea7023 feat: 增强测试用例以支持函数调用和输出，优化工具参数处理逻辑 2026-03-02 23:11:38 +08:00
ciat-777 555f6e15ab feat: enhance tool call handling and serialization in chat formats 
- Added support for tool calls in NormalizedFinalResponse type.
- Implemented functions to collect and serialize tool calls from OpenAI and Claude responses.
- Updated convertClaudeRequestToOpenAiBody to handle tool use and tool result messages.
- Enhanced normalizeUpstreamFinalResponse to include tool calls in the response structure.
- Introduced utility functions for safe JSON stringification and parsing.
- Improved conversion functions for OpenAI tools to Anthropic format and vice versa.
- Updated input handling in convertOpenAiBodyToMessagesBody and convertOpenAiBodyToResponsesBody to accommodate tool messages.
- Refactored serialization logic in serializeFinalResponse and buildSyntheticOpenAiChunks to include tool calls.
 2026-03-02 22:18:13 +08:00
ciat-777 515d083b2c feat: 添加 Zeabur 一键部署指南和相关变量说明 2026-03-02 21:08:07 +08:00
ciat-777 ed2b30c347 fix: 更新 Dockerfile，添加缺失的依赖项安装 2026-03-02 20:51:20 +08:00
ciat-777 605c5e1959 refactor: 更新未知平台的端点优先级逻辑 2026-03-02 20:46:02 +08:00
ciat-777 487bd23a02 Add platform adapters and tests for CLIProxyAPI, OneHub, Sub2API, and title hint detection 
- Implemented `CliProxyApiAdapter` with detection logic for CLIProxyAPI.
- Added tests for `CliProxyApiAdapter` to verify detection and response handling.
- Created `OneHubAdapter` with methods for fetching models and user groups.
- Added tests for `OneHubAdapter` to ensure correct fallback and response parsing.
- Developed `Sub2ApiAdapter` with detection and user info fetching capabilities.
- Added comprehensive tests for `Sub2ApiAdapter` covering various scenarios.
- Introduced `TitleHintPlatform` type and detection logic based on HTML title.
- Implemented tests for title hint detection to identify platforms from URLs.
 2026-03-02 20:26:02 +08:00
ciat-777 897273fad4 fix: 更新 Zeabur 部署链接和按钮样式 2026-03-02 17:34:08 +08:00
cita 264a12ed00 feat: 添加 Zeabur 部署模板和相关文档 2026-03-02 16:14:59 +08:00
cita 9471d3359b Merge branch 'main' of https://github.com/cita-777/metapi 2026-03-02 15:35:44 +08:00
cita 946907d66c Refactor code structure for improved readability and maintainability 2026-03-02 15:35:40 +08:00
Cita 515fcf1aaf Merge pull request #16 from cita-777/imgbot 
[ImgBot] Optimize images
 2026-03-02 14:46:13 +08:00
ImgBotApp 24f4b4aa56 [ImgBot] Optimize images 
*Total -- 13,493.63kb -> 8,824.35kb (34.6%)

/docs/screenshots/account-balance.png -- 152.01kb -> 86.31kb (43.22%)
/docs/logos/drafts/logo1.png -- 5,242.26kb -> 3,141.12kb (40.08%)
/docs/screenshots/token-management.png -- 156.86kb -> 97.87kb (37.61%)
/docs/logos/logo.png -- 123.83kb -> 77.82kb (37.15%)
/docs/logos/logo-icon-128.png -- 34.64kb -> 21.89kb (36.81%)
/docs/logos/logo-icon-512.png -- 477.52kb -> 308.22kb (35.45%)
/src/web/public/logo.png -- 477.52kb -> 308.22kb (35.45%)
/docs/logos/drafts/logo2.png -- 1,789.13kb -> 1,186.45kb (33.69%)
/docs/logos/drafts/logo3.png -- 1,230.31kb -> 844.78kb (31.34%)
/docs/logos/logo-icon-64.png -- 9.81kb -> 6.77kb (30.99%)
/docs/screenshots/accounts.png -- 474.50kb -> 328.72kb (30.72%)
/docs/screenshots/dashboard.png -- 680.18kb -> 473.10kb (30.44%)
/docs/screenshots/model-marketplace.png -- 566.33kb -> 394.13kb (30.41%)
/docs/screenshots/routes.png -- 598.34kb -> 419.06kb (29.96%)
/docs/logos/logo-banner.png -- 94.92kb -> 67.79kb (28.58%)
/docs/screenshots/account-management.png -- 680.25kb -> 496.13kb (27.07%)
/docs/logos/logo-banner-sm.png -- 31.83kb -> 23.79kb (25.26%)
/docs/logos/logo-full.png -- 121.20kb -> 90.99kb (24.92%)
/docs/screenshots/allapi-hub-backup.png -- 193.06kb -> 145.82kb (24.47%)
/docs/screenshots/site-management.png -- 78.36kb -> 61.36kb (21.7%)
/docs/logos/logo-full-sm.png -- 40.96kb -> 32.34kb (21.06%)
/src/web/public/favicon-64.png -- 5.31kb -> 4.31kb (18.96%)
/docs/logos/logo-icon-32.png -- 2.84kb -> 2.32kb (18.11%)
/docs/screenshots/account-credentials.png -- 231.67kb -> 205.04kb (11.5%)

Signed-off-by: ImgBotApp <ImgBotHelp@gmail.com>
 2026-03-02 06:42:36 +00:00
cita a3f55a83f9 Refactor code structure for improved readability and maintainability 2026-03-02 14:37:49 +08:00
cita f6389a999a feat(tests): add comprehensive tests for TokenRouter and related components 
- Implement tests for TokenRouter downstream policy, covering allowedRouteIds and site weight multipliers.
- Add tests for TokenRouter patterns and model mapping, including regex pattern matching and model mapping precedence.
- Create tests for BrandIcon component to verify brand detection logic.
- Develop tests for Accounts page, focusing on rebind panel behavior and refresh action on error.
- Introduce fuzzy search utility tests to validate substring and subsequence matching.
- Implement navigation focus helpers tests for building and parsing focus paths.
- Add progressive render tests to ensure correct initial and next visible counts.
- Create route model candidates index tests to validate route candidate indexing and matching logic.
 2026-03-02 13:33:35 +08:00
cita 99c9e145c3 feat: 更新 Dockerfile 2026-03-01 18:17:04 +08:00
cita 5c1bbd0c62 feat: 更新 Dockerfile 和启动脚本，改用 Debian slim 基础镜像，增强 Node.js ABI 兼容性检查 2026-03-01 17:52:36 +08:00
cita 05a5ee9b9e feat: enhance upstream endpoint handling with new passthrough header extraction and response management 
- Introduced new types for endpoint preferences to support 'responses'.
- Added functions to extract safe passthrough headers, Claude-specific headers, and responses-specific headers.
- Implemented logic to ensure proper handling of stream accept headers.
- Updated endpoint resolution logic to prioritize 'responses' in certain contexts.
- Enhanced request building for 'messages' and 'responses' endpoints with improved body sanitization and header management.
- Added comprehensive documentation for new features and usage instructions.
 2026-03-01 17:26:50 +08:00
cita af63df808d Merge branch 'main' of https://github.com/cita-777/metapi 2026-03-01 16:19:17 +08:00
cita 906e8328d6 feat: 添加发布工作流和启动脚本，支持直接运行预打包的 Release 产物 2026-03-01 16:19:14 +08:00
Cita a667aad3d0 Update Star History Chart link with version 2026-03-01 16:08:40 +08:00
cita e41b6b7993 feat: 增强设置功能，支持当前识别的管理 IP 和白名单更新逻辑 2026-03-01 15:39:13 +08:00
cita 4d6cd683b3 Merge branch 'main' of https://github.com/cita-777/metapi 2026-03-01 15:21:19 +08:00
cita 4e22b379a8 feat: Add support for OpenAI Responses endpoint and enhance proxy retry logic 
- Updated proxyRetryPolicy to retry on all 4xx and 5xx status codes.
- Introduced 'responses' target format in TestChatRequestPayload.
- Implemented extractResponsesContent function to handle responses format in ModelTester.
- Enhanced ModelTester to support responses target format and display appropriate labels.
- Updated ProxyLogs to extract and display upstream paths from error messages.
- Added tests to ensure responses target format is preserved during payload sync.
- Created responses proxy route to handle requests to the new OpenAI Responses endpoint.
- Updated upstreamEndpoint logic to include responses endpoint handling.
- Added modelService tests to validate token route rebuilding logic.
 2026-03-01 15:21:16 +08:00
Cita d6698e5da0 Update Star History chart link and parameters 2026-03-01 01:19:44 +08:00
cita 44af9a91cf feat: add sorting and pinning functionality for accounts and sites 
- Introduced `isPinned` and `sortOrder` fields in the `accounts` and `sites` tables to allow users to pin and sort their accounts and sites.
- Updated API routes to handle pinning and sorting operations for accounts and sites.
- Enhanced the frontend to support sorting by balance and custom order, as well as toggling the pin status of accounts and sites.
- Added tests for sorting and reordering logic to ensure correct functionality.
- Updated documentation to reflect changes in token management and new features.
 2026-02-28 23:45:30 +08:00
cita 08eaf11ea2 feat: 添加 Docker 发布工作流以支持多架构镜像构建 2026-02-28 22:50:46 +08:00
cita f75459f8bf feat: 添加表存在性检查以确保数据库模式的完整性 2026-02-28 22:26:05 +08:00
cita 9405d468d9 Add initial database schema and journal entries for token management 
- Created a new snapshot JSON file (0003_snapshot.json) defining the schema for tables including account_tokens, accounts, checkin_logs, events, model_availability, proxy_logs, route_channels, settings, sites, token_model_availability, and token_routes.
- Added columns, indexes, and foreign key constraints for each table to ensure data integrity and relationships.
- Introduced a journal JSON file (_journal.json) to track schema versions and changes, including entries for version 6 with relevant tags and timestamps.
 2026-02-28 22:20:28 +08:00
cita 2eeebbd686 docs: 修复 README.md 中的格式问题，移除多余的反引号 2026-02-28 17:45:02 +08:00
cita 9892770052 docs: 清理 README.md，移除冗余链接和占位符 2026-02-28 17:36:14 +08:00
cita 63481caa8b Refactor code structure for improved readability and maintainability 2026-02-28 17:30:34 +08:00
cita 20eec09211 docs: 更新 README.md，优化内容格式和结构 2026-02-28 00:40:13 +08:00
cita 2ecc23730d chore: initialize clean metapi repository 2026-02-28 00:36:28 +08:00
695 changed files with 261375 additions and 2 deletions
Expand all files Collapse all files
.cargo/config.toml
+33
View File
@@ -0,0 +1,33 @@
# Cargo build acceleration.
#
# The biggest single speedup is the `mold` linker (~3-5x faster link
# time on debug builds). `build-and-run.sh` enables mold/lld automatically
# when available, so the block below is kept as an optional manual setup for
# direct `cargo build` / `cargo run` usage:
#
# sudo apt-get install -y mold
#
# (or build it from source: https://github.com/rui314/mold)
#
# Without mold/lld, the [profile.dev] tweaks in Cargo.toml still give a
# meaningful speedup (line-tables-only debuginfo + bumped codegen-units).
# Optional: uncomment once mold is on PATH if you want direct cargo commands
# to use it without going through build-and-run.sh.
# [target.x86_64-unknown-linux-gnu]
# linker = "clang"
# rustflags = ["-C", "link-arg=-fuse-ld=mold"]
[build]
# Default to all CPUs for parallel codegen. Override with --jobs N if
# you need to leave headroom for other work.
# jobs = 8
# sccache compilation cache: caches compiled crates keyed by source+flags,
# so clean builds and branch switches reuse prior results. sccache transparently
# skips crates built with incremental compilation (dev profile), so it mainly
# accelerates release/fast-release and dependency rebuilds. Harmless if absent
# — cargo only applies this when the binary exists on PATH via build-and-run.sh,
# which sets RUSTC_WRAPPER conditionally. Uncomment to force it for direct cargo:
# rustc-wrapper = "sccache"
.codegraph/.gitignore
+16
View File
@@ -0,0 +1,16 @@
# CodeGraph data files
# These are local to each machine and should not be committed
# Database
*.db
*.db-wal
*.db-shm
# Cache
cache/
# Logs
*.log
# Hook markers
.dirty
.dockerignore
+20
View File
@@ -0,0 +1,20 @@
comfy_source/venv
comfy_source/.git
comfy_source/__pycache__
**/__pycache__
target/
node_modules/
dist/
release/
data/
logs/
tmp/
.agents/
.cache/
.codex/
.claude/
.comfyui/
boosapi
bossai
boosapi.db
docker/*.tar
.env.test
+1
View File
@@ -0,0 +1 @@
NODE_ENV=test
.gitignore
+33
View File
@@ -0,0 +1,33 @@
/target
**/*.rs.bk
.env
.env.*
data/
node_modules/
website/.next/
website/out/
dist/
release/
*.log
*.tsbuildinfo
logs/
tmp/
!tmp/.gitkeep
.DS_Store
Thumbs.db
docker/data/
docker/.env
.ace-tool/
.comfyui/
.claude/
.codex/
.agents/
.cache/
openspec/
boosapi
bossai
docker/*.tar
boosapi.db-shm
boosapi.db-wal
.tours/
bun.lock
.gitmodules
+4
View File
@@ -0,0 +1,4 @@
[submodule "vendor/ComfyUI_frontend"]
path = vendor/ComfyUI_frontend
url = https://github.com/Comfy-Org/ComfyUI_frontend.git
branch = main
.trellis/.gitignore
+32
View File
@@ -0,0 +1,32 @@
# Developer identity (local only)
.developer
# Current task pointer (each dev works on different task)
.current-task
# Session/window scoped runtime state
.runtime/
# Ralph Loop state file
.ralph-state.json
# Agent runtime files
.agents/
.agent-log
.session-id
# Task directory runtime files
.plan-log
# Atomic update temp files
*.tmp
# Update backup directories
.backup-*
# Conflict resolution temp files
*.new
# Python cache
**/__pycache__/
**/*.pyc
.trellis/.template-hashes.json
+140
View File
@@ -0,0 +1,140 @@
{
"__version": 2,
"hashes": {
".claude/agents/trellis-check.md": "9e48342243f311d55386f8fb42933945e87aba73d5ade547133aa98345a06128",
".claude/agents/trellis-implement.md": "73b56b3047c0e852382c4630aa181fb847d1e5ea1f63459dac4bf728f43fd097",
".claude/agents/trellis-research.md": "add4aa4259ded425b04ec992802c646490352bb4eb3730a7ab450beea87d4faa",
".claude/hooks/inject-subagent-context.py": "c8ea04062990530dffb26c4d1efa3e6887e042d3086da2f2325b491c9d544931",
".claude/hooks/inject-workflow-state.py": "f7fa9389ed7aa264597fff5de6277bec186e89a3ef539192997c6d026d88d5ec",
".claude/hooks/session-start.py": "2cd87a08dec8cecc5f1acb665d6bd7241bc580f6ae39d571b99a0118be89c46b",
".claude/commands/trellis/continue.md": "6c34c41824f8eff4b2df792e032e0c36787b59f8a8879b0338347073f76ad52c",
".claude/commands/trellis/finish-work.md": "d6aa570ab684f57e4845de2d84a1ff6d9f0908e04c5a56e14fd70ae739c369fc",
".claude/skills/trellis-before-dev/SKILL.md": "859894f2e8258cbfa142d710363433761c54984c69f7ed7bd44512fb4eb165cd",
".claude/skills/trellis-brainstorm/SKILL.md": "219f99c61e59aa9af4642c0ec96ceec72c915f6757572760ba69dee951b05eb1",
".claude/skills/trellis-break-loop/SKILL.md": "f5a93699832f29dee443b53c135a7459519b371f689af191d15c29e8ee5c7bde",
".claude/skills/trellis-check/SKILL.md": "b21ff04b7680ebacb8c5ecbc48a22d627eb13e2b47fceb78c8ced0b43b60b282",
".claude/skills/trellis-update-spec/SKILL.md": "d975db7af166578488958751ae2c56edb827a68bddb569aa27acc3453f64e610",
".claude/skills/trellis-channel/references/command-reference.md": "c4df3d940d89814310bfdaded20e84dd1d6b96786f6772688de7a123338d3c8e",
".claude/skills/trellis-channel/references/forum.md": "407db39e8ebde47cea8637e3069bdb3d76ba42b43ed1d08ba97a56f26dbcfcb4",
".claude/skills/trellis-channel/references/progress-debugging.md": "93b021fd8d5d3d4ee54952c40424ab91ca57c2ab8032bfbfc3b5c5e22f1464cd",
".claude/skills/trellis-channel/references/workers.md": "d4481b2858bca82050cb8d131916da8a2ccc3857f199cdb9ced8bb41d592e2a7",
".claude/skills/trellis-channel/references/workflows.md": "0782d602efde6e94a7d7d7950fd605eedc9a1f5a523908284e76b628fd618fd4",
".claude/skills/trellis-channel/SKILL.md": "ff84801c511a736da018b4b1149348ebc9a16b7fc18d905ec10cfa7acbf269a3",
".claude/skills/trellis-meta/references/customize-local/add-project-local-conventions.md": "86009ccb5d0373f399582da0bc570c4e5c6053c3c764857424ff93384f0e04e5",
".claude/skills/trellis-meta/references/customize-local/change-agents.md": "3eef0d9b9cf875f121c1a38afb8eee6d3cd3894127db601ae5a7760fa5b61575",
".claude/skills/trellis-meta/references/customize-local/change-context-loading.md": "350d319dc1ab99609ddbf52cf8c06c71bd97ba1a29ce2eac8b97d0bb192938bf",
".claude/skills/trellis-meta/references/customize-local/change-hooks.md": "91892f2cff53ae003736007e95172945acabf48b2fc889bd627cd2406ce449c4",
".claude/skills/trellis-meta/references/customize-local/change-skills-or-commands.md": "a6994e2418cdf5bcad10b4236b02741179ae794bc4fdd811a64f443293b69268",
".claude/skills/trellis-meta/references/customize-local/change-spec-structure.md": "31eccaad7097d96e66a45c1b4caea1ba4f2e54b7814184c3ebf82c87dafc4841",
".claude/skills/trellis-meta/references/customize-local/change-task-lifecycle.md": "60ff9efb93604b87a461a4af30322d76750402a51e40f31531a7ff88d309996d",
".claude/skills/trellis-meta/references/customize-local/change-workflow.md": "43fa780a2ca580de121b10893d49b99f978873deebbf45008c466e5ac6651519",
".claude/skills/trellis-meta/references/customize-local/overview.md": "ce8f09e9f93ce9a48500763fb3a4db2b3908a5fbf4f985ab71dacebb404cf8f4",
".claude/skills/trellis-meta/references/local-architecture/bundled-skills.md": "bac739b042d7a12dae5d14d85cbc312e56ca03f571d2ba7a25b20641ddaefc3f",
".claude/skills/trellis-meta/references/local-architecture/context-injection.md": "8497289bf333b3aa456f317039d1239b7ece79254aa0eb62cfc647714c866084",
".claude/skills/trellis-meta/references/local-architecture/generated-files.md": "ca4211b43aff79cf263c83255f557994386723d10da344c0c4e1ec211c7fcd37",
".claude/skills/trellis-meta/references/local-architecture/multi-agent-channel.md": "56e5070474aeca872e2d70c46feea5aaafecd3d3ec052c3f7b1877358dca62e9",
".claude/skills/trellis-meta/references/local-architecture/overview.md": "50638fd9eaaba2e0edf2f2a84d920578d5b2fb7934031b174e417d3dc510b2a6",
".claude/skills/trellis-meta/references/local-architecture/spec-system.md": "b8d8a6a0888b44a232c8f50161b9e20e903cf621ad7be4021715ab6fab226f47",
".claude/skills/trellis-meta/references/local-architecture/task-system.md": "2b561d49c390f7d0db5391912946133be4bf73189231e2b8cc9afa1c5ac6165a",
".claude/skills/trellis-meta/references/local-architecture/workflow.md": "cfcdc6e4468a5d9c816e929fcca01640cd41cfdaaa4824118b40a8e460c927b6",
".claude/skills/trellis-meta/references/local-architecture/workspace-memory.md": "e6427b46aba744563c2444b30df4043cd856561b7709ec2dece26095416421fd",
".claude/skills/trellis-meta/references/platform-files/agents.md": "ce1a22c2b3ff0bff68755b5663e1f3b63ef2f1658cff43e511cee9013537c698",
".claude/skills/trellis-meta/references/platform-files/hooks-and-settings.md": "b70f983d0b3fea45e4ad7abef8ab8981473ff016d6d454d4d407865c13019d31",
".claude/skills/trellis-meta/references/platform-files/overview.md": "7bc24f5ffefe082f373562bbba715cce9e761a76f6b59ce341d4dc679971a587",
".claude/skills/trellis-meta/references/platform-files/platform-map.md": "a3cb8b4b4e42a3b380485aca673750ba3b2b28c16a04339b1db7afbd479509ab",
".claude/skills/trellis-meta/references/platform-files/skills-and-commands.md": "5732bb0a7d384a91abd0c103372f3865e0b186e75185f35e0e91b00a6b6bf5a3",
".claude/skills/trellis-meta/SKILL.md": "a190ecbde70a658a5b5c3e2558783e99c9afc6f2e5cdecdac8f11c06dd42065e",
".claude/skills/trellis-session-insight/references/cli-quick-reference.md": "c520353fe3fc00b9702ed4f780647c8fbd6d342e66527a03647f533a9fe09779",
".claude/skills/trellis-session-insight/references/triggering-patterns.md": "121ecd23be83d1567e8ce15c366a81073d7a2b1d3ad616fce235c07ca1f1cc20",
".claude/skills/trellis-session-insight/SKILL.md": "f6ad80eaca21b8fa63d31ae26b612bb2bb69dd04469603828509a8c5a0463ff1",
".claude/skills/trellis-spec-bootstrap/references/mcp-setup.md": "df542fc8f279edd38046d26a7c8151804b708f57b24d4aa2733cea587a88c65e",
".claude/skills/trellis-spec-bootstrap/references/repository-analysis.md": "0dae98d774f6e34559b9f3442888ac43e3a8af110c37cbefc49ce256986858b6",
".claude/skills/trellis-spec-bootstrap/references/spec-task-planning.md": "ef493d028c3b0807a8a534bb71fb92a68129f273db763ad27ceb464a522e799d",
".claude/skills/trellis-spec-bootstrap/references/spec-writing.md": "e9800fe9ed4a4cd87062ea1829cf2caa8d170ec15e141678a6a30e74c497f47d",
".claude/skills/trellis-spec-bootstrap/SKILL.md": "97bfa68c06cebb558eb4464bc1b81f7d2d56040d75baa8de1ee5ad90cca0196a",
".agents/skills/trellis-continue/SKILL.md": "7723ccf49fbf19d8f086cacc7a080bd8be8db6fc70a32908b80f68efa318d7bf",
".agents/skills/trellis-finish-work/SKILL.md": "161060fbcd44f787440d3a5c297a9f5223ea7774bb3021a50e376875a9ac5b2d",
".agents/skills/trellis-before-dev/SKILL.md": "859894f2e8258cbfa142d710363433761c54984c69f7ed7bd44512fb4eb165cd",
".agents/skills/trellis-brainstorm/SKILL.md": "219f99c61e59aa9af4642c0ec96ceec72c915f6757572760ba69dee951b05eb1",
".agents/skills/trellis-break-loop/SKILL.md": "f5a93699832f29dee443b53c135a7459519b371f689af191d15c29e8ee5c7bde",
".agents/skills/trellis-check/SKILL.md": "b21ff04b7680ebacb8c5ecbc48a22d627eb13e2b47fceb78c8ced0b43b60b282",
".agents/skills/trellis-update-spec/SKILL.md": "003ce08a3404aeb50998029392c4d4e57b626edf526d3ebd585032bb92dcbb96",
".agents/skills/trellis-channel/references/command-reference.md": "c4df3d940d89814310bfdaded20e84dd1d6b96786f6772688de7a123338d3c8e",
".agents/skills/trellis-channel/references/forum.md": "407db39e8ebde47cea8637e3069bdb3d76ba42b43ed1d08ba97a56f26dbcfcb4",
".agents/skills/trellis-channel/references/progress-debugging.md": "93b021fd8d5d3d4ee54952c40424ab91ca57c2ab8032bfbfc3b5c5e22f1464cd",
".agents/skills/trellis-channel/references/workers.md": "d4481b2858bca82050cb8d131916da8a2ccc3857f199cdb9ced8bb41d592e2a7",
".agents/skills/trellis-channel/references/workflows.md": "0782d602efde6e94a7d7d7950fd605eedc9a1f5a523908284e76b628fd618fd4",
".agents/skills/trellis-channel/SKILL.md": "ff84801c511a736da018b4b1149348ebc9a16b7fc18d905ec10cfa7acbf269a3",
".agents/skills/trellis-meta/references/customize-local/add-project-local-conventions.md": "86009ccb5d0373f399582da0bc570c4e5c6053c3c764857424ff93384f0e04e5",
".agents/skills/trellis-meta/references/customize-local/change-agents.md": "3eef0d9b9cf875f121c1a38afb8eee6d3cd3894127db601ae5a7760fa5b61575",
".agents/skills/trellis-meta/references/customize-local/change-context-loading.md": "350d319dc1ab99609ddbf52cf8c06c71bd97ba1a29ce2eac8b97d0bb192938bf",
".agents/skills/trellis-meta/references/customize-local/change-hooks.md": "91892f2cff53ae003736007e95172945acabf48b2fc889bd627cd2406ce449c4",
".agents/skills/trellis-meta/references/customize-local/change-skills-or-commands.md": "a6994e2418cdf5bcad10b4236b02741179ae794bc4fdd811a64f443293b69268",
".agents/skills/trellis-meta/references/customize-local/change-spec-structure.md": "31eccaad7097d96e66a45c1b4caea1ba4f2e54b7814184c3ebf82c87dafc4841",
".agents/skills/trellis-meta/references/customize-local/change-task-lifecycle.md": "60ff9efb93604b87a461a4af30322d76750402a51e40f31531a7ff88d309996d",
".agents/skills/trellis-meta/references/customize-local/change-workflow.md": "43fa780a2ca580de121b10893d49b99f978873deebbf45008c466e5ac6651519",
".agents/skills/trellis-meta/references/customize-local/overview.md": "ce8f09e9f93ce9a48500763fb3a4db2b3908a5fbf4f985ab71dacebb404cf8f4",
".agents/skills/trellis-meta/references/local-architecture/bundled-skills.md": "bac739b042d7a12dae5d14d85cbc312e56ca03f571d2ba7a25b20641ddaefc3f",
".agents/skills/trellis-meta/references/local-architecture/context-injection.md": "8497289bf333b3aa456f317039d1239b7ece79254aa0eb62cfc647714c866084",
".agents/skills/trellis-meta/references/local-architecture/generated-files.md": "ca4211b43aff79cf263c83255f557994386723d10da344c0c4e1ec211c7fcd37",
".agents/skills/trellis-meta/references/local-architecture/multi-agent-channel.md": "56e5070474aeca872e2d70c46feea5aaafecd3d3ec052c3f7b1877358dca62e9",
".agents/skills/trellis-meta/references/local-architecture/overview.md": "50638fd9eaaba2e0edf2f2a84d920578d5b2fb7934031b174e417d3dc510b2a6",
".agents/skills/trellis-meta/references/local-architecture/spec-system.md": "b8d8a6a0888b44a232c8f50161b9e20e903cf621ad7be4021715ab6fab226f47",
".agents/skills/trellis-meta/references/local-architecture/task-system.md": "2b561d49c390f7d0db5391912946133be4bf73189231e2b8cc9afa1c5ac6165a",
".agents/skills/trellis-meta/references/local-architecture/workflow.md": "cfcdc6e4468a5d9c816e929fcca01640cd41cfdaaa4824118b40a8e460c927b6",
".agents/skills/trellis-meta/references/local-architecture/workspace-memory.md": "e6427b46aba744563c2444b30df4043cd856561b7709ec2dece26095416421fd",
".agents/skills/trellis-meta/references/platform-files/agents.md": "ce1a22c2b3ff0bff68755b5663e1f3b63ef2f1658cff43e511cee9013537c698",
".agents/skills/trellis-meta/references/platform-files/hooks-and-settings.md": "b70f983d0b3fea45e4ad7abef8ab8981473ff016d6d454d4d407865c13019d31",
".agents/skills/trellis-meta/references/platform-files/overview.md": "7bc24f5ffefe082f373562bbba715cce9e761a76f6b59ce341d4dc679971a587",
".agents/skills/trellis-meta/references/platform-files/platform-map.md": "a3cb8b4b4e42a3b380485aca673750ba3b2b28c16a04339b1db7afbd479509ab",
".agents/skills/trellis-meta/references/platform-files/skills-and-commands.md": "5732bb0a7d384a91abd0c103372f3865e0b186e75185f35e0e91b00a6b6bf5a3",
".agents/skills/trellis-meta/SKILL.md": "a190ecbde70a658a5b5c3e2558783e99c9afc6f2e5cdecdac8f11c06dd42065e",
".agents/skills/trellis-session-insight/references/cli-quick-reference.md": "c520353fe3fc00b9702ed4f780647c8fbd6d342e66527a03647f533a9fe09779",
".agents/skills/trellis-session-insight/references/triggering-patterns.md": "121ecd23be83d1567e8ce15c366a81073d7a2b1d3ad616fce235c07ca1f1cc20",
".agents/skills/trellis-session-insight/SKILL.md": "f6ad80eaca21b8fa63d31ae26b612bb2bb69dd04469603828509a8c5a0463ff1",
".agents/skills/trellis-spec-bootstrap/references/mcp-setup.md": "df542fc8f279edd38046d26a7c8151804b708f57b24d4aa2733cea587a88c65e",
".agents/skills/trellis-spec-bootstrap/references/repository-analysis.md": "0dae98d774f6e34559b9f3442888ac43e3a8af110c37cbefc49ce256986858b6",
".agents/skills/trellis-spec-bootstrap/references/spec-task-planning.md": "ef493d028c3b0807a8a534bb71fb92a68129f273db763ad27ceb464a522e799d",
".agents/skills/trellis-spec-bootstrap/references/spec-writing.md": "e9800fe9ed4a4cd87062ea1829cf2caa8d170ec15e141678a6a30e74c497f47d",
".agents/skills/trellis-spec-bootstrap/SKILL.md": "97bfa68c06cebb558eb4464bc1b81f7d2d56040d75baa8de1ee5ad90cca0196a",
".agents/skills/trellis-start/SKILL.md": "79a5ba7a2aff3c72e06d7f4cd6942dc4f4f4092dd40f9c8e94f1838024a81e4d",
".codex/agents/trellis-check.toml": "372dbd32a68f156727fd9f5d755a184543db96013abfeaffb09974c78fd5b873",
".codex/agents/trellis-implement.toml": "87dc719802b355c61607c85ae0ab3e42b2a374a578a9fde349c3ae412638f8b4",
".codex/agents/trellis-research.toml": "5492f7f6ab8bdea975b0e853bf171b050f7ddf6c2079ac770ed912c48d815eae",
".codex/hooks/session-start.py": "1c951ff35f490c5fbf576b4764ec190895df7c2a48e279fb20625209f51c321a",
".codex/hooks/inject-workflow-state.py": "f7fa9389ed7aa264597fff5de6277bec186e89a3ef539192997c6d026d88d5ec",
".codex/hooks.json": "522ba3c488c100027783e52ecff84c0bd799852dd77ad3f1936e86db105f01d6",
".trellis/agents/check.md": "edb4f57361407249a53bf5998ebf91c40d2b969e826a2c5e1b4e813a08bcb175",
".trellis/agents/implement.md": "66e25ad046c94869442834bc3cdfbd5a9a7412d3ff54561d64d2886552c27e87",
".trellis/config.yaml": "2e6489de5ab99c501f24edd3f08df977801bf49c33b04a2de6afafe35a3a8332",
".trellis/scripts/__init__.py": "1242be5b972094c2e141aecbe81a4efd478f6534e3d5e28306374e6a18fcf46c",
".trellis/scripts/add_session.py": "7fcacb29ffd13599949a517aa967d868040eb4c9b40356b0c460a32361237eb6",
".trellis/scripts/common/__init__.py": "3d5e9347141f0296319a5beb29d69ae714c5a474b9078caeb3edd7c5f6562e22",
".trellis/scripts/common/active_task.py": "6c88ed40ef7289bca0f6d2ecba0f8b8aef46cd58788080fbeeea88de138a431f",
".trellis/scripts/common/cli_adapter.py": "bda2eb3a76b3990ef979846a5eff3d8aedde9c70e0e9d128266034aeee186020",
".trellis/scripts/common/config.py": "25c5a53ad20d6909be5209222e4208a84528805316a4d78350529459a364edb1",
".trellis/scripts/common/developer.py": "f5f833123abe68890171b4da825a324216d24913f6b5ad9245afc556424ffd7b",
".trellis/scripts/common/git.py": "e14817be7de122d3a106f509c2825aeb9669d962ba73ba241642d2931cfdf1d6",
".trellis/scripts/common/git_context.py": "fa30ced454f1a91ffc9f8b2abeb32225e3447cbdc90bad783797374eba07265d",
".trellis/scripts/common/io.py": "6480b181f2bc505323b28ed7a66963d7b7edc96251e83b4c8e7a45907cc721c8",
".trellis/scripts/common/log.py": "471df6895cfac80f995edebbf9974f6b7440634b7a688f28b8331c868bc0f3cf",
".trellis/scripts/common/packages_context.py": "efe158d7c99c2268851d0216fbb08de22836e418a8dbeb73575b8cc249eed7b7",
".trellis/scripts/common/paths.py": "05898ef136cc7c4d861b05fbf2b16d53ddd3e6f311a231d4fcfcb81bde7c45ee",
".trellis/scripts/common/safe_commit.py": "baa5c82324eb62154374ec63394ecdc8609bb37d93892e3bcb88f452bb7d6446",
".trellis/scripts/common/session_context.py": "df79c44efe3432811c32d145d57a66343a70e221ec087ed2bd28b76677bb4076",
".trellis/scripts/common/task_context.py": "d174684d417bbe2fafc26b6afcddb264c7dc519527bb24d2055cd27daaad9b55",
".trellis/scripts/common/task_queue.py": "0be61f713462b1fe4574927c82fc4704e678afe72dcb9813543aedf2f9e9e0c5",
".trellis/scripts/common/task_store.py": "789c090c2d5103bf790e8bfb0989a8ff486c7d370cbe03d3eefb1c239d02624a",
".trellis/scripts/common/task_utils.py": "f5ef4af87ba3e11d8b19630c0c96d009de1811fc9be56c2027a9c96e21ed103e",
".trellis/scripts/common/tasks.py": "4436a8b0b53c270a35989e26d9dbd92669408c6562d88c02083a404562da85fe",
".trellis/scripts/common/trellis_config.py": "0839dcf90ebbd77712c276930a89335b3313927051650c91d220fb51ca2a6a3c",
".trellis/scripts/common/types.py": "9962081cc2608fb9d1deb32c6880e336f62cdca6b338e7ae813304701e155ee9",
".trellis/scripts/common/workflow_phase.py": "f2b5fcf0c40cedcf3d7d0ad8023d141fa4095caf0302d73f2a73e1bc04b5692b",
".trellis/scripts/get_context.py": "ca5bf9e90bdb1d75d3de182b95f820f9d108ab28793d29097b24fd71315adcf5",
".trellis/scripts/get_developer.py": "84c27076323c3e0f2c9c8ed16e8aa865e225d902a187c37e20ee1a46e7142d8f",
".trellis/scripts/hooks/linear_sync.py": "e09cc4ce4699aada908808718698f33f705a3edf55c4dcf8f777ad892f80ca79",
".trellis/scripts/init_developer.py": "f9e6c0d882406e81c8cd6b1c5abb204b0befc0069ff89cf650cd536a80f8c60e",
".trellis/scripts/task.py": "6c65801a1f56648fd4765a1d216493d3094827c1db4761e55fdaa548c1801798",
".trellis/workflow.md": "f44acd1c08d1601fdc4377671ef932eb3e09f0e87b7872a6d0ee4baeada29fcb"
}
}
.trellis/.version
+1
View File
@@ -0,0 +1 @@
0.6.3
.trellis/agents/check.md
+70
View File
@@ -0,0 +1,70 @@
---
name: check
description: |
Code quality auditor for the Trellis channel runtime. Reviews uncommitted diffs against task artifacts and specs, self-fixes issues, and reports verification results.
provider: claude
labels: [trellis, check]
---
# Check Agent (channel runtime)
You are the Check Agent spawned by `trellis channel spawn --agent check` inside the Trellis channel runtime. You receive an `Active task: <path>` line in your inbox; use it to locate task artifacts on disk.
## Context
Before reviewing, read in this order:
1. `<task-path>/check.jsonl` if present — spec manifest curated for this turn; read every listed file
2. `<task-path>/prd.md` — requirements
3. `<task-path>/design.md` if present — technical design
4. `<task-path>/implement.md` if present — execution plan
5. `.trellis/spec/` — project-wide guidelines (load only what is relevant to the diff under review)
## Core Responsibilities
1. **Get the diff** — `git diff` / `git diff --staged` for uncommitted changes
2. **Review against task artifacts** — does the diff satisfy `prd.md` (and `design.md` / `implement.md` if present)?
3. **Review against specs** — naming, structure, type safety, error handling, conventions in `.trellis/spec/`
4. **Self-fix** — when an issue is mechanical and small, fix it directly with the editing tools you have
5. **Run verification** — project lint and typecheck on the changed scope
6. **Report** — concrete findings with `file:line` citations and what was fixed vs. what is open
## Forbidden Operations
- `git commit`
- `git push`
- `git merge`
The supervising main session owns commits. Report the post-fix state; do not commit on its behalf.
## Workflow
1. Run `git diff --name-only` and `git diff` to scope the changes
2. Read the task artifacts and relevant spec files
3. For each issue:
- If mechanical (lint nit, missing type, wrong import, dead branch) → fix in-place
- If a design/judgment issue → record and report, do not silently rewrite
4. Run the project's lint and typecheck on the changed scope after self-fixes
5. Report
## Report Format
```
## Self-Check Complete
### Files Checked
- <path>
### Issues Found and Fixed
1. `<file>:<line>` — <what was wrong> → <what you changed>
### Issues Not Fixed
- `<file>:<line>` — <issue> — <why deferred to the main session>
### Verification Results
- TypeCheck: <pass|fail|skipped + reason>
- Lint: <pass|fail|skipped + reason>
### Summary
Checked <N> files, found <X> issues, fixed <Y>, <X-Y> open.
```
.trellis/agents/implement.md
+71
View File
@@ -0,0 +1,71 @@
---
name: implement
description: |
Code implementation expert for the Trellis channel runtime. Understands specs and task artifacts, then implements features. No git commit allowed.
provider: claude
labels: [trellis, implement]
---
# Implement Agent (channel runtime)
You are the Implement Agent spawned by `trellis channel spawn --agent implement` inside the Trellis channel runtime. You receive an `Active task: <path>` line in your inbox; use it to locate task artifacts on disk.
## Context
Before implementing, read in this order:
1. `<task-path>/implement.jsonl` if present — spec manifest curated for this turn; read every listed file
2. `<task-path>/prd.md` — requirements
3. `<task-path>/design.md` if present — technical design
4. `<task-path>/implement.md` if present — execution plan
5. `.trellis/spec/` — project-wide guidelines (load only what is relevant to the diff you are about to write)
## Core Responsibilities
1. **Understand specs** — read relevant spec files in `.trellis/spec/`
2. **Understand task artifacts** — read the artifacts listed above
3. **Implement features** — write code that follows specs and existing patterns
4. **Self-check** — run lint and typecheck on the changed scope before reporting
## Forbidden Operations
- `git commit`
- `git push`
- `git merge`
The supervising main session owns commits. Report what changed; do not commit on its behalf.
## Workflow
1. Read relevant specs based on task type and the files in `implement.jsonl` if present
2. Read the task's `prd.md`, `design.md` if present, and `implement.md` if present
3. Implement features following specs and existing patterns
4. Run the project's lint and typecheck commands on the changed scope
5. Report files touched, key decisions, and verification results back to the channel
## Code Standards
- Follow existing code patterns
- Don't add unnecessary abstractions
- Only do what the PRD asks for; no speculative scope expansion
- Surface uncertainty back to the channel rather than guessing
## Report Format
```
## Implementation Complete
### Files Modified
- <path> — <one-line description>
### Implementation Summary
1. <step>
2. <step>
### Verification Results
- Lint: <pass|fail|skipped + reason>
- TypeCheck: <pass|fail|skipped + reason>
### Open Questions
- <if any, otherwise omit>
```
.trellis/config.yaml
+117
View File
@@ -0,0 +1,117 @@
# Trellis Configuration
# Project-level settings for the Trellis workflow system
#
# All values have sensible defaults. Only override what you need.
#-------------------------------------------------------------------------------
# Session Recording
#-------------------------------------------------------------------------------
# Commit message used when auto-committing journal/index changes
# after running add_session.py
session_commit_message: "chore: record journal"
# Maximum lines per journal file before rotating to a new one
max_journal_lines: 2000
#-------------------------------------------------------------------------------
# Session Auto-Commit
#-------------------------------------------------------------------------------
# Auto-commit behavior for session journal + task archive operations.
# - true (default): scripts auto-stage and auto-commit journal / task changes
# after add_session.py / task.py archive runs.
# - false: scripts do not touch git. Files (journal-*.md, task archive moves)
# are still written to disk; you decide whether to git add / commit.
#
# Use `false` if your project's .gitignore intentionally excludes `.trellis/`
# and you want session data kept local-only, or if you prefer to review
# staged changes manually before each commit.
#
# Accepts: true / false / yes / no / 1 / 0 / on / off (case-insensitive).
#
# session_auto_commit: true
#-------------------------------------------------------------------------------
# Task Lifecycle Hooks
#-------------------------------------------------------------------------------
# Shell commands to run after task lifecycle events.
# Each hook receives TASK_JSON_PATH environment variable pointing to task.json.
# Hook failures print a warning but do not block the main operation.
#
# hooks:
# after_create:
# - "echo 'Task created'"
# after_start:
# - "echo 'Task started'"
# after_finish:
# - "echo 'Task finished'"
# after_archive:
# - "echo 'Task archived'"
#-------------------------------------------------------------------------------
# Monorepo / Packages
#-------------------------------------------------------------------------------
# Declare packages for monorepo projects.
# Trellis auto-detects workspaces during `trellis init`, but you can also
# configure them manually here.
#
# packages:
# frontend:
# path: packages/frontend
# backend:
# path: packages/backend
# docs:
# path: docs-site
# type: submodule
# # For polyrepo / meta-repo layouts (independent .git in each subdir),
# # mark the package with `git: true`. The runtime treats it as an
# # independent repository for things like git-context display.
# webapp:
# path: ./webapp
# git: true
# Default package used when --package is not specified.
# default_package: frontend
#-------------------------------------------------------------------------------
# Channel worker OOM guard
#-------------------------------------------------------------------------------
# Default safeguards for `trellis channel spawn` workers. The guard runs
# at spawn time (cleans expired idle workers, then enforces the live-worker
# budget) and inside each supervisor (self-terminates a worker that stays
# continuously idle past `idle_timeout`).
#
# Precedence: CLI flag > env var (TRELLIS_CHANNEL_WORKER_IDLE_TIMEOUT /
# TRELLIS_CHANNEL_MAX_LIVE_WORKERS) > this config > built-in default.
#
# `idle_timeout: 0` disables idle cleanup (workers can sit idle forever
# unless explicitly killed or given `--timeout`).
# `max_live_workers: 0` disables the spawn-time budget check.
#
channel:
worker_guard:
idle_timeout: 5m
max_live_workers: 6
#-------------------------------------------------------------------------------
# Codex (dispatch behavior)
#-------------------------------------------------------------------------------
# Codex-only knob; other platforms ignore it. Default ("inline") makes the
# main Codex agent edit code directly because Codex sub-agents run with
# `fork_turns="none"` isolation and can't inherit the parent session's
# task context. Set to "sub-agent" to opt into the legacy dispatch model
# (main agent spawns trellis-implement / trellis-check / trellis-research
# sub-agents).
#
# codex:
# dispatch_mode: inline # or "sub-agent" to dispatch trellis-* sub-agents
# Auto-detected monorepo packages
packages:
vendor/ComfyUI_frontend:
path: vendor/ComfyUI_frontend
type: submodule
default_package: vendor/ComfyUI_frontend
.trellis/scripts/__init__.py
Executable
+5
View File
@@ -0,0 +1,5 @@
"""
Trellis Python Scripts
This module provides Python implementations of Trellis workflow scripts.
"""
.trellis/scripts/add_session.py
Executable
+567
View File
@@ -0,0 +1,567 @@
#!/usr/bin/env python3
# -*- coding: utf-8 -*-
"""
Add a new session to journal file and update index.md.
Usage:
python3 add_session.py --title "Title" --commit "hash" --summary "Summary" [--package cli]
python3 add_session.py --title "Title" --branch "feat/my-branch"
# Pipe detailed content via stdin (use --stdin to opt in):
cat << 'EOF' | python3 add_session.py --stdin --title "Title" --summary "Summary"
<session content here>
EOF
Branch resolution order:
1. --branch CLI arg (explicit)
2. task.json branch field (from active task)
3. git branch --show-current (auto-detect)
4. None (omitted gracefully)
"""
from __future__ import annotations
import argparse
import re
import sys
from datetime import datetime
from pathlib import Path
from common.paths import (
DIR_TASKS,
DIR_WORKFLOW,
FILE_JOURNAL_PREFIX,
get_repo_root,
get_current_task,
get_developer,
get_workspace_dir,
)
from common.developer import ensure_developer
from common.git import run_git
from common.safe_commit import (
print_gitignore_warning,
safe_git_add,
safe_trellis_paths_to_add,
)
from common.tasks import load_task
from common.config import (
get_packages,
get_session_auto_commit,
get_session_commit_message,
get_max_journal_lines,
is_monorepo,
resolve_package,
validate_package,
)
# =============================================================================
# Helper Functions
# =============================================================================
def get_latest_journal_info(dev_dir: Path) -> tuple[Path | None, int, int]:
"""Get latest journal file info.
Returns:
Tuple of (file_path, file_number, line_count).
"""
latest_file: Path | None = None
latest_num = -1
for f in dev_dir.glob(f"{FILE_JOURNAL_PREFIX}*.md"):
if not f.is_file():
continue
match = re.search(r"(\d+)$", f.stem)
if match:
num = int(match.group(1))
if num > latest_num:
latest_num = num
latest_file = f
if latest_file:
lines = len(latest_file.read_text(encoding="utf-8").splitlines())
return latest_file, latest_num, lines
return None, 0, 0
def get_current_session(index_file: Path) -> int:
"""Get current session number from index.md."""
if not index_file.is_file():
return 0
content = index_file.read_text(encoding="utf-8")
for line in content.splitlines():
if "Total Sessions" in line:
match = re.search(r":\s*(\d+)", line)
if match:
return int(match.group(1))
return 0
def _extract_journal_num(filename: str) -> int:
"""Extract journal number from filename for sorting."""
match = re.search(r"(\d+)", filename)
return int(match.group(1)) if match else 0
def count_journal_files(dev_dir: Path, active_num: int) -> str:
"""Count journal files and return table rows."""
active_file = f"{FILE_JOURNAL_PREFIX}{active_num}.md"
result_lines = []
files = sorted(
[f for f in dev_dir.glob(f"{FILE_JOURNAL_PREFIX}*.md") if f.is_file()],
key=lambda f: _extract_journal_num(f.stem),
reverse=True
)
for f in files:
filename = f.name
lines = len(f.read_text(encoding="utf-8").splitlines())
status = "Active" if filename == active_file else "Archived"
result_lines.append(f"| `{filename}` | ~{lines} | {status} |")
return "\n".join(result_lines)
def create_new_journal_file(
dev_dir: Path, num: int, developer: str, today: str, max_lines: int = 2000,
) -> Path:
"""Create a new journal file."""
prev_num = num - 1
new_file = dev_dir / f"{FILE_JOURNAL_PREFIX}{num}.md"
content = f"""# Journal - {developer} (Part {num})
> Continuation from `{FILE_JOURNAL_PREFIX}{prev_num}.md` (archived at ~{max_lines} lines)
> Started: {today}
---
"""
new_file.write_text(content, encoding="utf-8")
return new_file
def generate_session_content(
session_num: int,
title: str,
commit: str,
summary: str,
extra_content: str,
today: str,
package: str | None = None,
branch: str | None = None,
) -> str:
"""Generate session content."""
if commit and commit != "-":
commit_table = """| Hash | Message |
|------|---------|"""
for c in commit.split(","):
c = c.strip()
commit_table += f"\n| `{c}` | (see git log) |"
else:
commit_table = "(No commits - planning session)"
package_line = f"\n**Package**: {package}" if package else ""
branch_line = f"\n**Branch**: `{branch}`" if branch else ""
return f"""
## Session {session_num}: {title}
**Date**: {today}
**Task**: {title}{package_line}{branch_line}
### Summary
{summary}
### Main Changes
{extra_content}
### Git Commits
{commit_table}
### Testing
- [OK] (Add test results)
### Status
[OK] **Completed**
### Next Steps
- None - task complete
"""
def update_index(
index_file: Path,
dev_dir: Path,
title: str,
commit: str,
new_session: int,
active_file: str,
today: str,
branch: str | None = None,
) -> bool:
"""Update index.md with new session info."""
# Format commit for display
commit_display = "-"
if commit and commit != "-":
commit_display = re.sub(r"([a-f0-9]{7,})", r"`\1`", commit.replace(",", ", "))
# Get file number from active_file name
match = re.search(r"(\d+)", active_file)
active_num = int(match.group(1)) if match else 0
files_table = count_journal_files(dev_dir, active_num)
print(f"Updating index.md for session {new_session}...")
print(f" Title: {title}")
print(f" Commit: {commit_display}")
print(f" Active File: {active_file}")
print()
content = index_file.read_text(encoding="utf-8")
if "@@@auto:current-status" not in content:
print("Error: Markers not found in index.md. Please ensure markers exist.", file=sys.stderr)
return False
# Process sections
lines = content.splitlines()
new_lines = []
in_current_status = False
in_active_documents = False
in_session_history = False
header_written = False
for line in lines:
if "@@@auto:current-status" in line:
new_lines.append(line)
in_current_status = True
new_lines.append(f"- **Active File**: `{active_file}`")
new_lines.append(f"- **Total Sessions**: {new_session}")
new_lines.append(f"- **Last Active**: {today}")
continue
if "@@@/auto:current-status" in line:
in_current_status = False
new_lines.append(line)
continue
if "@@@auto:active-documents" in line:
new_lines.append(line)
in_active_documents = True
new_lines.append("| File | Lines | Status |")
new_lines.append("|------|-------|--------|")
new_lines.append(files_table)
continue
if "@@@/auto:active-documents" in line:
in_active_documents = False
new_lines.append(line)
continue
if "@@@auto:session-history" in line:
new_lines.append(line)
in_session_history = True
header_written = False
continue
if "@@@/auto:session-history" in line:
in_session_history = False
new_lines.append(line)
continue
if in_current_status:
continue
if in_active_documents:
continue
if in_session_history:
# Migrate old 4/6-column headers to 5-column Branch-only history.
if re.match(
r"^\|\s*#\s*\|\s*Date\s*\|\s*Title\s*\|\s*Commits\s*\|\s*Branch\s*\|\s*Base Branch\s*\|\s*$",
line,
):
new_lines.append("| # | Date | Title | Commits | Branch |")
continue
if re.match(r"^\|\s*#\s*\|\s*Date\s*\|\s*Title\s*\|\s*Commits\s*\|\s*Branch\s*\|\s*$", line):
new_lines.append("| # | Date | Title | Commits | Branch |")
continue
if re.match(r"^\|\s*#\s*\|\s*Date\s*\|\s*Title\s*\|\s*Commits\s*\|\s*$", line):
new_lines.append("| # | Date | Title | Commits | Branch |")
continue
if re.match(r"^\|[-| ]+\|\s*$", line) and not header_written:
new_lines.append("|---|------|-------|---------|--------|")
new_lines.append(f"| {new_session} | {today} | {title} | {commit_display} | `{branch or '-'}` |")
header_written = True
continue
new_lines.append(line)
continue
new_lines.append(line)
index_file.write_text("\n".join(new_lines), encoding="utf-8")
print("[OK] Updated index.md successfully!")
return True
# =============================================================================
# Main Function
# =============================================================================
def _auto_commit_workspace(repo_root: Path) -> None:
"""Stage Trellis-owned workspace + current-task paths and commit.
Path scope is restricted to specific products: the current developer's
journal files + index.md, and ONLY the current task directory (resolved
via ``get_current_task``). We never `git add` the whole `.trellis/` tree
or iterate over all active task dirs (#303: parallel-window dirty task
dirs must not be bundled into the session auto-commit). If `.gitignore`
blocks the specific paths we warn + skip — never retry with ``-f``.
Honors ``session_auto_commit`` in ``.trellis/config.yaml``: when set to
``false``, this function returns immediately without touching git
(journal/index files are still written to disk by the caller).
"""
if not get_session_auto_commit(repo_root):
print(
"[OK] session_auto_commit: false — skipping git stage/commit.",
file=sys.stderr,
)
return
commit_msg = get_session_commit_message(repo_root)
# Resolve the current task so staging is scoped to its dir only. The ref
# is ``.trellis/tasks/<name>`` (or under archive/) — pass the bare name.
current = get_current_task(repo_root)
if current:
task_name = Path(current).name
paths = safe_trellis_paths_to_add(repo_root, task_name=task_name)
else:
# Current task unknown (0 or >=2 parallel sessions — exactly the
# parallel-window case #303 is about). Do NOT fall back to the wide
# `tasks_dir.iterdir()` scan; that would re-leak other tasks' dirty
# dirs into the session commit. Stage only the developer's journal/
# index and skip every task dir.
paths = [
p
for p in safe_trellis_paths_to_add(repo_root, task_name=None)
if not p.startswith(f"{DIR_WORKFLOW}/{DIR_TASKS}/")
]
if not paths:
print("[OK] No workspace changes to commit.", file=sys.stderr)
return
success, _, err = safe_git_add(paths, repo_root)
if not success:
if err and "ignored by" in err.lower():
print_gitignore_warning(paths)
else:
print(
f"[WARN] git add failed: {err.strip() if err else 'unknown error'}",
file=sys.stderr,
)
return
# Check if there are staged changes for the paths we just staged.
rc, _, _ = run_git(
["diff", "--cached", "--quiet", "--", *paths], cwd=repo_root
)
if rc == 0:
print("[OK] No workspace changes to commit.", file=sys.stderr)
return
rc, _, commit_err = run_git(["commit", "-m", commit_msg], cwd=repo_root)
if rc == 0:
print(f"[OK] Auto-committed: {commit_msg}", file=sys.stderr)
else:
print(
f"[WARN] Auto-commit failed: {commit_err.strip()}",
file=sys.stderr,
)
def add_session(
title: str,
commit: str = "-",
summary: str = "(Add summary)",
extra_content: str = "(Add details)",
auto_commit: bool = True,
package: str | None = None,
branch: str | None = None,
) -> int:
"""Add a new session."""
repo_root = get_repo_root()
ensure_developer(repo_root)
developer = get_developer(repo_root)
if not developer:
print("Error: Developer not initialized", file=sys.stderr)
return 1
dev_dir = get_workspace_dir(repo_root)
if not dev_dir:
print("Error: Workspace directory not found", file=sys.stderr)
return 1
max_lines = get_max_journal_lines(repo_root)
index_file = dev_dir / "index.md"
today = datetime.now().strftime("%Y-%m-%d")
journal_file, current_num, current_lines = get_latest_journal_info(dev_dir)
current_session = get_current_session(index_file)
new_session = current_session + 1
session_content = generate_session_content(
new_session, title, commit, summary, extra_content, today, package,
branch,
)
content_lines = len(session_content.splitlines())
print("========================================", file=sys.stderr)
print("ADD SESSION", file=sys.stderr)
print("========================================", file=sys.stderr)
print("", file=sys.stderr)
print(f"Session: {new_session}", file=sys.stderr)
print(f"Title: {title}", file=sys.stderr)
print(f"Commit: {commit}", file=sys.stderr)
print("", file=sys.stderr)
print(f"Current journal file: {FILE_JOURNAL_PREFIX}{current_num}.md", file=sys.stderr)
print(f"Current lines: {current_lines}", file=sys.stderr)
print(f"New content lines: {content_lines}", file=sys.stderr)
print(f"Total after append: {current_lines + content_lines}", file=sys.stderr)
print("", file=sys.stderr)
target_file = journal_file
target_num = current_num
if current_lines + content_lines > max_lines:
target_num = current_num + 1
print(f"[!] Exceeds {max_lines} lines, creating {FILE_JOURNAL_PREFIX}{target_num}.md", file=sys.stderr)
target_file = create_new_journal_file(dev_dir, target_num, developer, today, max_lines)
print(f"Created: {target_file}", file=sys.stderr)
# Append session content
if target_file:
with target_file.open("a", encoding="utf-8") as f:
f.write(session_content)
print(f"[OK] Appended session to {target_file.name}", file=sys.stderr)
print("", file=sys.stderr)
# Update index.md
active_file = f"{FILE_JOURNAL_PREFIX}{target_num}.md"
if not update_index(
index_file,
dev_dir,
title,
commit,
new_session,
active_file,
today,
branch,
):
return 1
print("", file=sys.stderr)
print("========================================", file=sys.stderr)
print(f"[OK] Session {new_session} added successfully!", file=sys.stderr)
print("========================================", file=sys.stderr)
print("", file=sys.stderr)
print("Files updated:", file=sys.stderr)
print(f" - {target_file.name if target_file else 'journal'}", file=sys.stderr)
print(" - index.md", file=sys.stderr)
# Auto-commit workspace changes
if auto_commit:
print("", file=sys.stderr)
_auto_commit_workspace(repo_root)
return 0
# =============================================================================
# Main Entry
# =============================================================================
def main() -> int:
"""CLI entry point."""
parser = argparse.ArgumentParser(
description="Add a new session to journal file and update index.md"
)
parser.add_argument("--title", required=True, help="Session title")
parser.add_argument("--commit", default="-", help="Comma-separated commit hashes")
parser.add_argument("--summary", default="(Add summary)", help="Brief summary")
parser.add_argument("--content-file", help="Path to file with detailed content")
parser.add_argument("--package", help="Package name tag (e.g., cli, docs-site)")
parser.add_argument("--branch", help="Branch name (auto-detected if omitted)")
parser.add_argument("--no-commit", action="store_true",
help="Skip auto-commit of workspace changes")
parser.add_argument("--stdin", action="store_true",
help="Read extra content from stdin (explicit opt-in)")
args = parser.parse_args()
extra_content = "(Add details)"
if args.content_file:
content_path = Path(args.content_file)
if content_path.is_file():
extra_content = content_path.read_text(encoding="utf-8")
elif args.stdin:
extra_content = sys.stdin.read()
# Load active task once — shared by package and branch resolution
repo_root = get_repo_root()
current = get_current_task(repo_root)
task_data = load_task(repo_root / current) if current else None
package = args.package
if package:
# CLI source: fail-fast in monorepo, ignore in single-repo
if not is_monorepo(repo_root):
print("Warning: --package ignored in single-repo project", file=sys.stderr)
package = None
elif not validate_package(package, repo_root):
packages = get_packages(repo_root)
available = ", ".join(sorted(packages.keys())) if packages else "(none)"
print(f"Error: unknown package '{package}'. Available: {available}", file=sys.stderr)
return 1
else:
# Inferred: active task's task.json.package → default_package → None
task_package = task_data.package if task_data else None
package = resolve_package(task_package, repo_root)
# Resolve branch: CLI → task.json → git auto-detect → None
branch = args.branch
if not branch:
if task_data and task_data.raw.get("branch"):
branch = task_data.raw["branch"]
else:
_, branch_out, _ = run_git(["branch", "--show-current"], cwd=repo_root)
detected = branch_out.strip()
if detected:
branch = detected
return add_session(
args.title, args.commit, args.summary, extra_content,
auto_commit=not args.no_commit,
package=package,
branch=branch,
)
if __name__ == "__main__":
sys.exit(main())
.trellis/scripts/common/__init__.py
Executable
+92
View File
@@ -0,0 +1,92 @@
"""
Common utilities for Trellis workflow scripts.
This module provides shared functionality used by other Trellis scripts.
"""
import io
import sys
# =============================================================================
# Windows Encoding Fix (MUST be at top, before any other output)
# =============================================================================
# On Windows, stdout defaults to the system code page (often GBK/CP936).
# This causes UnicodeEncodeError when printing non-ASCII characters.
#
# Any script that imports from common will automatically get this fix.
# =============================================================================
def _configure_stream(stream: object) -> object:
"""Configure a stream for UTF-8 encoding on Windows."""
# Try reconfigure() first (Python 3.7+, more reliable)
if hasattr(stream, "reconfigure"):
stream.reconfigure(encoding="utf-8", errors="replace") # type: ignore[union-attr]
return stream
# Fallback: detach and rewrap with TextIOWrapper
elif hasattr(stream, "detach"):
return io.TextIOWrapper(
stream.detach(), # type: ignore[union-attr]
encoding="utf-8",
errors="replace",
)
return stream
if sys.platform == "win32":
sys.stdout = _configure_stream(sys.stdout) # type: ignore[assignment]
sys.stderr = _configure_stream(sys.stderr) # type: ignore[assignment]
sys.stdin = _configure_stream(sys.stdin) # type: ignore[assignment]
def configure_encoding() -> None:
"""
Configure stdout/stderr/stdin for UTF-8 encoding on Windows.
This is automatically called when importing from common,
but can be called manually for scripts that don't import common.
Safe to call multiple times.
"""
global sys
if sys.platform == "win32":
sys.stdout = _configure_stream(sys.stdout) # type: ignore[assignment]
sys.stderr = _configure_stream(sys.stderr) # type: ignore[assignment]
sys.stdin = _configure_stream(sys.stdin) # type: ignore[assignment]
from .paths import (
DIR_WORKFLOW,
DIR_WORKSPACE,
DIR_TASKS,
DIR_ARCHIVE,
DIR_SPEC,
DIR_SCRIPTS,
FILE_DEVELOPER,
FILE_CURRENT_TASK,
FILE_TASK_JSON,
FILE_JOURNAL_PREFIX,
get_repo_root,
get_developer,
check_developer,
get_tasks_dir,
get_workspace_dir,
get_active_journal_file,
count_lines,
get_current_task,
get_current_task_abs,
normalize_task_ref,
resolve_task_ref,
set_current_task,
clear_current_task,
has_current_task,
generate_task_date_prefix,
)
from .active_task import (
ActiveTask,
clear_active_task,
resolve_active_task,
resolve_context_key,
set_active_task,
)
.trellis/scripts/common/active_task.py
Executable
+626
View File
@@ -0,0 +1,626 @@
#!/usr/bin/env python3
"""Session-scoped active task resolution.
The user-facing concept is a single "active task". Trellis stores that pointer
per AI session/window under `.trellis/.runtime/sessions/`; without a stable
session key there is no active task.
"""
from __future__ import annotations
import hashlib
import json
import os
import re
import sys
import time
from dataclasses import dataclass
from datetime import datetime, timezone
from pathlib import Path
from typing import Any
DIR_WORKFLOW = ".trellis"
DIR_TASKS = "tasks"
DIR_RUNTIME = ".runtime"
DIR_SESSIONS = "sessions"
DIR_CURSOR_SHELL = "cursor-shell"
CURSOR_SHELL_TICKET_TTL_SECONDS = 30
TASK_SESSION_COMMANDS = {"start", "current", "finish"}
_SESSION_KEYS = ("session_id", "sessionId", "sessionID")
_CONVERSATION_KEYS = ("conversation_id", "conversationId", "conversationID")
_TRANSCRIPT_KEYS = ("transcript_path", "transcriptPath", "transcript")
_NESTED_KEYS = ("input", "properties", "event", "hook_input", "hookInput")
_KNOWN_PLATFORMS = {
"claude",
"codex",
"cursor",
"opencode",
"gemini",
"droid",
"qoder",
"codebuddy",
"kiro",
"copilot",
"pi",
}
_ENV_SESSION_KEYS: tuple[tuple[str, tuple[str, ...]], ...] = (
("claude", ("CLAUDE_SESSION_ID", "CLAUDE_CODE_SESSION_ID")),
("codex", ("CODEX_SESSION_ID", "CODEX_THREAD_ID")),
("cursor", ("CURSOR_SESSION_ID",)),
("opencode", ("OPENCODE_SESSION_ID", "OPENCODE_SESSIONID", "OPENCODE_RUN_ID")),
("gemini", ("GEMINI_SESSION_ID",)),
("droid", ("FACTORY_SESSION_ID", "DROID_SESSION_ID")),
("qoder", ("QODER_SESSION_ID",)),
("codebuddy", ("CODEBUDDY_SESSION_ID",)),
("kiro", ("KIRO_SESSION_ID",)),
("copilot", ("COPILOT_SESSION_ID", "COPILOT_SESSIONID")),
("pi", ("PI_SESSION_ID", "PI_SESSIONID")),
)
_ENV_CONVERSATION_KEYS: tuple[tuple[str, tuple[str, ...]], ...] = (
("cursor", ("CURSOR_CONVERSATION_ID", "CURSOR_CONVERSATIONID")),
)
_ENV_TRANSCRIPT_KEYS: tuple[tuple[str, tuple[str, ...]], ...] = (
("claude", ("CLAUDE_TRANSCRIPT_PATH",)),
("codex", ("CODEX_TRANSCRIPT_PATH",)),
("cursor", ("CURSOR_TRANSCRIPT_PATH",)),
("gemini", ("GEMINI_TRANSCRIPT_PATH",)),
("droid", ("FACTORY_TRANSCRIPT_PATH", "DROID_TRANSCRIPT_PATH")),
("qoder", ("QODER_TRANSCRIPT_PATH",)),
("codebuddy", ("CODEBUDDY_TRANSCRIPT_PATH",)),
)
_ENV_PLATFORM_ALIASES = {
"claude-code": "claude",
"factory": "droid",
"factory-ai": "droid",
"github-copilot": "copilot",
}
@dataclass(frozen=True)
class ActiveTask:
"""Resolved active task state."""
task_path: str | None
source_type: str
context_key: str | None = None
stale: bool = False
@property
def source(self) -> str:
"""Human-readable source label."""
if self.source_type == "session" and self.context_key:
return f"session:{self.context_key}"
if self.source_type == "session-fallback" and self.context_key:
return f"session-fallback:{self.context_key}"
return self.source_type
def normalize_task_ref(task_ref: str) -> str:
"""Normalize a task ref for stable storage and comparison."""
normalized = task_ref.strip()
if not normalized:
return ""
path_obj = Path(normalized)
if path_obj.is_absolute():
return str(path_obj)
normalized = normalized.replace("\\", "/")
while normalized.startswith("./"):
normalized = normalized[2:]
if normalized.startswith(f"{DIR_TASKS}/"):
return f"{DIR_WORKFLOW}/{normalized}"
return normalized
def resolve_task_ref(task_ref: str, repo_root: Path) -> Path | None:
"""Resolve a task ref to an absolute task directory."""
normalized = normalize_task_ref(task_ref)
if not normalized:
return None
path_obj = Path(normalized)
if path_obj.is_absolute():
return path_obj
if normalized.startswith(f"{DIR_WORKFLOW}/"):
return repo_root / path_obj
return repo_root / DIR_WORKFLOW / DIR_TASKS / path_obj
def _runtime_sessions_dir(repo_root: Path) -> Path:
return repo_root / DIR_WORKFLOW / DIR_RUNTIME / DIR_SESSIONS
def _sanitize_key(raw: str) -> str:
safe = re.sub(r"[^A-Za-z0-9._-]+", "_", raw.strip())
safe = safe.strip("._-")
return safe[:160] if safe else ""
def _hash_value(raw: str) -> str:
return hashlib.sha256(raw.encode("utf-8")).hexdigest()[:24]
def _as_dict(value: Any) -> dict[str, Any] | None:
return value if isinstance(value, dict) else None
def _string_value(value: Any) -> str | None:
if isinstance(value, str):
stripped = value.strip()
return stripped or None
return None
def _lookup_string(data: dict[str, Any], keys: tuple[str, ...]) -> str | None:
for key in keys:
value = _string_value(data.get(key))
if value:
return value
for nested_key in _NESTED_KEYS:
nested = _as_dict(data.get(nested_key))
if not nested:
continue
value = _lookup_string(nested, keys)
if value:
return value
return None
def _detect_platform(platform_input: dict[str, Any] | None, platform: str | None) -> str:
if platform:
return _sanitize_key(platform) or "session"
if platform_input:
for key in ("_trellis_platform", "trellis_platform", "platform", "source"):
value = _string_value(platform_input.get(key))
if value:
return _sanitize_key(value) or "session"
if _string_value(platform_input.get("cursor_version")):
return "cursor"
return "session"
def _context_key(platform_name: str, kind: str, value: str) -> str:
if kind == "transcript":
return f"{platform_name}_transcript_{_hash_value(value)}"
safe_value = _sanitize_key(value)
if safe_value:
return f"{platform_name}_{safe_value}"
return f"{platform_name}_{_hash_value(value)}"
def _iter_env_keys(
env_keys: tuple[tuple[str, tuple[str, ...]], ...],
platform_name: str | None,
) -> tuple[tuple[str, tuple[str, ...]], ...]:
if not platform_name:
return env_keys
matched = tuple((name, keys) for name, keys in env_keys if name == platform_name)
return matched
def _env_platform_name(platform_name: str | None) -> str | None:
if not platform_name or platform_name == "session":
return None
return _ENV_PLATFORM_ALIASES.get(platform_name, platform_name)
def _lookup_env_context_key(platform_name: str | None) -> str | None:
"""Resolve a context key from platform-provided environment variables.
Hooks pass `TRELLIS_CONTEXT_ID` to subprocesses they launch, but an AI-run
shell command can only see session identity if the host platform exports it
in the command environment. These names are best-effort adapters; if none
are present, there is no session-scoped active task.
"""
env_platform_name = _env_platform_name(platform_name)
for name, keys in _iter_env_keys(_ENV_SESSION_KEYS, env_platform_name):
for key in keys:
value = _string_value(os.environ.get(key))
if value:
return _context_key(name, "session", value)
for name, keys in _iter_env_keys(_ENV_CONVERSATION_KEYS, env_platform_name):
for key in keys:
value = _string_value(os.environ.get(key))
if value:
return _context_key(name, "conversation", value)
for name, keys in _iter_env_keys(_ENV_TRANSCRIPT_KEYS, env_platform_name):
for key in keys:
value = _string_value(os.environ.get(key))
if value:
return _context_key(name, "transcript", value)
return None
def _find_repo_root_from_cwd() -> Path | None:
current = Path.cwd().resolve()
while True:
if (current / DIR_WORKFLOW).is_dir():
return current
if current == current.parent:
return None
current = current.parent
def _cursor_shell_ticket_dir(repo_root: Path) -> Path:
return repo_root / DIR_WORKFLOW / DIR_RUNTIME / DIR_CURSOR_SHELL
def _remove_file(path: Path) -> bool:
try:
path.unlink()
return True
except OSError:
return False
def _task_refs_match(left: str | None, right: str | None, repo_root: Path) -> bool:
if not left or not right:
return False
left_path = resolve_task_ref(left, repo_root)
right_path = resolve_task_ref(right, repo_root)
if left_path is not None and right_path is not None:
return left_path == right_path
return normalize_task_ref(left) == normalize_task_ref(right)
def _pending_ticket_matches_args(ticket: dict[str, Any], repo_root: Path) -> bool:
if Path(sys.argv[0]).name != "task.py":
return False
args = tuple(sys.argv[1:])
if not args:
return False
command_name = args[0]
if command_name not in TASK_SESSION_COMMANDS:
return False
subcommands = ticket.get("subcommands")
if not isinstance(subcommands, list):
return False
for subcommand in subcommands:
if not isinstance(subcommand, dict):
continue
if _string_value(subcommand.get("name")) != command_name:
continue
if command_name != "start":
return True
task_ref = args[1] if len(args) > 1 else None
if _task_refs_match(_string_value(subcommand.get("task_ref")), task_ref, repo_root):
return True
return False
def _ticket_is_fresh(ticket: dict[str, Any], ticket_path: Path, now: float) -> bool:
expires_at = ticket.get("expires_at_epoch")
if isinstance(expires_at, (int, float)) and expires_at < now:
_remove_file(ticket_path)
return False
created_at = ticket.get("created_at_epoch")
if isinstance(created_at, (int, float)):
if now - created_at <= CURSOR_SHELL_TICKET_TTL_SECONDS:
return True
_remove_file(ticket_path)
return False
return True
def _ticket_cwd_matches_repo(ticket: dict[str, Any], repo_root: Path) -> bool:
cwd = _string_value(ticket.get("cwd"))
if not cwd:
return True
try:
Path(cwd).resolve().relative_to(repo_root)
except ValueError:
return False
return True
def _matching_cursor_ticket_context_key(
ticket_path: Path,
repo_root: Path,
now: float,
) -> str | None:
ticket = _read_json(ticket_path)
if ticket is None or ticket.get("platform") != "cursor":
return None
if not _ticket_is_fresh(ticket, ticket_path, now):
return None
if not _ticket_cwd_matches_repo(ticket, repo_root):
return None
if not _pending_ticket_matches_args(ticket, repo_root):
return None
return _string_value(ticket.get("context_key"))
def _lookup_cursor_shell_ticket_context_key() -> str | None:
"""Resolve Cursor conversation identity from a short-lived shell ticket.
Cursor exposes `conversation_id` to `beforeShellExecution`, but does not
export it into the shell command environment. The Cursor hook writes a
short-lived ticket just before `task.py` runs. We accept a ticket only when
the current `task.py` subcommand matches and exactly one fresh context key
matches, which avoids cross-window pointer contamination.
"""
repo_root = _find_repo_root_from_cwd()
if repo_root is None:
return None
ticket_dir = _cursor_shell_ticket_dir(repo_root)
if not ticket_dir.is_dir():
return None
now = time.time()
candidates: set[str] = set()
for ticket_path in ticket_dir.glob("*.json"):
context_key = _matching_cursor_ticket_context_key(ticket_path, repo_root, now)
if context_key:
candidates.add(context_key)
if len(candidates) == 1:
return next(iter(candidates))
return None
def resolve_context_key(
platform_input: dict[str, Any] | None = None,
platform: str | None = None,
) -> str | None:
"""Resolve a stable session/window context key, if one is available.
`TRELLIS_CONTEXT_ID` is an explicit context-key override used by CLI
scripts and subprocesses. It does not store the task itself.
"""
override = _string_value(os.environ.get("TRELLIS_CONTEXT_ID"))
if override:
return _sanitize_key(override) or _hash_value(override)
data = _as_dict(platform_input)
platform_name = _detect_platform(data, platform) if data or platform else None
if data:
session_id = _lookup_string(data, _SESSION_KEYS)
if session_id:
return _context_key(platform_name or "session", "session", session_id)
conversation_id = _lookup_string(data, _CONVERSATION_KEYS)
if conversation_id:
return _context_key(platform_name or "session", "conversation", conversation_id)
transcript_path = _lookup_string(data, _TRANSCRIPT_KEYS)
if transcript_path:
return _context_key(platform_name or "session", "transcript", transcript_path)
env_context_key = _lookup_env_context_key(platform_name)
if env_context_key:
return env_context_key
if platform_name in (None, "session", "cursor"):
return _lookup_cursor_shell_ticket_context_key()
return None
def _read_json(path: Path) -> dict[str, Any] | None:
try:
data = json.loads(path.read_text(encoding="utf-8"))
except (FileNotFoundError, json.JSONDecodeError, OSError):
return None
return data if isinstance(data, dict) else None
def _write_json(path: Path, data: dict[str, Any]) -> bool:
try:
path.parent.mkdir(parents=True, exist_ok=True)
path.write_text(
json.dumps(data, indent=2, ensure_ascii=False) + "\n",
encoding="utf-8",
)
return True
except OSError:
return False
def _canonical_task_ref(task_path: str, repo_root: Path) -> str | None:
normalized = normalize_task_ref(task_path)
if not normalized:
return None
full_path = resolve_task_ref(normalized, repo_root)
if full_path is None or not full_path.is_dir():
return None
try:
return full_path.relative_to(repo_root).as_posix()
except ValueError:
return str(full_path)
def _active_from_ref(
task_ref: str | None,
repo_root: Path,
source_type: str,
context_key: str | None = None,
) -> ActiveTask | None:
if not task_ref:
return None
resolved = resolve_task_ref(task_ref, repo_root)
stale = resolved is None or not resolved.is_dir()
return ActiveTask(task_ref, source_type, context_key, stale)
def _context_path(repo_root: Path, context_key: str) -> Path:
return _runtime_sessions_dir(repo_root) / f"{context_key}.json"
def resolve_active_task(
repo_root: Path,
platform_input: dict[str, Any] | None = None,
platform: str | None = None,
) -> ActiveTask:
"""Resolve the active task from session runtime state only.
A stale session task is returned as stale. Missing context identity or a
missing/empty session context falls back to single-session inference: if
exactly one session file exists in the runtime, return its task with
source_type="session-fallback" — covers class-2 platform sub-agents (codex,
copilot, gemini, qoder) that don't inherit the parent's session id. ≥2
files or 0 files yield ActiveTask(None) — refuses to guess across windows.
"""
context_key = resolve_context_key(platform_input, platform)
if context_key:
context = _read_json(_context_path(repo_root, context_key)) or {}
task_ref = _string_value(context.get("current_task"))
active = _active_from_ref(task_ref, repo_root, "session", context_key)
if active:
return active
fallback = _resolve_single_session_fallback(repo_root)
if fallback is not None:
return fallback
return ActiveTask(None, "none", context_key)
def _resolve_single_session_fallback(repo_root: Path) -> ActiveTask | None:
"""Return the task pointed at by the sole session file, if exactly one exists.
Used when context-key resolution fails (typical for class-2 platform
sub-agents). Returns None if 0 or ≥2 session files are present — refuses
to pick across windows so 04-21's multi-session isolation contract holds.
"""
sessions_dir = _runtime_sessions_dir(repo_root)
if not sessions_dir.is_dir():
return None
session_files = sorted(sessions_dir.glob("*.json"))
if len(session_files) != 1:
return None
session_file = session_files[0]
context = _read_json(session_file) or {}
task_ref = _string_value(context.get("current_task"))
if not task_ref:
return None
fallback_key = session_file.stem
return _active_from_ref(task_ref, repo_root, "session-fallback", fallback_key)
def _utc_now() -> str:
return datetime.now(timezone.utc).replace(microsecond=0).isoformat().replace("+00:00", "Z")
def _context_metadata(
platform_input: dict[str, Any] | None,
platform: str | None,
context_key: str | None = None,
) -> dict[str, Any]:
data = _as_dict(platform_input) or {}
platform_name = _detect_platform(data, platform)
if platform_name == "session" and context_key:
prefix = context_key.split("_", 1)[0]
if prefix in _KNOWN_PLATFORMS:
platform_name = prefix
metadata: dict[str, Any] = {
"platform": platform_name,
"last_seen_at": _utc_now(),
}
for key in (*_SESSION_KEYS, *_CONVERSATION_KEYS, *_TRANSCRIPT_KEYS):
value = _lookup_string(data, (key,))
if value:
metadata[key] = value
return metadata
def set_active_task(
task_path: str,
repo_root: Path,
platform_input: dict[str, Any] | None = None,
platform: str | None = None,
) -> ActiveTask | None:
"""Set the active task in session scope.
Returns None when no context key is available; callers should surface a
user-facing error that explains how to provide session identity.
"""
canonical = _canonical_task_ref(task_path, repo_root)
if canonical is None:
return None
context_key = resolve_context_key(platform_input, platform)
if not context_key:
return None
context_path = _context_path(repo_root, context_key)
context = _read_json(context_path) or {}
context.update(_context_metadata(platform_input, platform, context_key))
context["current_task"] = canonical
context.setdefault("current_run", None)
if not _write_json(context_path, context):
return None
return ActiveTask(canonical, "session", context_key)
def clear_active_task(
repo_root: Path,
platform_input: dict[str, Any] | None = None,
platform: str | None = None,
) -> ActiveTask:
"""Clear the active task by deleting the current session context file."""
context_key = resolve_context_key(platform_input, platform)
if not context_key:
return ActiveTask(None, "none")
previous = resolve_active_task(repo_root, platform_input, platform)
context_path = _context_path(repo_root, context_key)
if context_path.is_file():
_remove_file(context_path)
return previous
def clear_task_from_sessions(task_path: str, repo_root: Path) -> int:
"""Delete all session runtime files that point at a task."""
target = _canonical_task_ref(task_path, repo_root) or normalize_task_ref(task_path)
if not target:
return 0
cleared = 0
sessions_dir = _runtime_sessions_dir(repo_root)
if not sessions_dir.is_dir():
return cleared
for session_path in sessions_dir.glob("*.json"):
context = _read_json(session_path) or {}
current = _string_value(context.get("current_task"))
if not current:
continue
current_ref = _canonical_task_ref(current, repo_root) or normalize_task_ref(current)
if current_ref != target:
continue
if session_path.is_file() and _remove_file(session_path):
cleared += 1
return cleared
def get_current_task_source(
repo_root: Path,
platform_input: dict[str, Any] | None = None,
platform: str | None = None,
) -> tuple[str, str | None, str | None]:
"""Return (`source_type`, `context_key`, `task_path`) for compatibility."""
active = resolve_active_task(repo_root, platform_input, platform)
return active.source_type, active.context_key, active.task_path
.trellis/scripts/common/cli_adapter.py
Executable
+825
View File
@@ -0,0 +1,825 @@
"""
CLI Adapter for Multi-Platform Support.
Abstracts differences between Claude Code, OpenCode, Cursor, iFlow, Codex, Kilo, Kiro Code, Gemini CLI, Antigravity, Devin, Qoder, CodeBuddy, GitHub Copilot, Factory Droid, and Pi Agent interfaces.
Supported platforms:
- claude: Claude Code (default)
- opencode: OpenCode
- cursor: Cursor IDE
- iflow: iFlow CLI
- codex: Codex CLI (skills-based)
- kilo: Kilo CLI
- kiro: Kiro Code (skills-based)
- gemini: Gemini CLI
- antigravity: Antigravity (workflow-based)
- devin: Devin (formerly Windsurf; workflow-based)
- qoder: Qoder
- codebuddy: CodeBuddy
- copilot: GitHub Copilot (VS Code)
- droid: Factory Droid (commands-based)
- pi: Pi Agent (extension-backed)
Usage:
from common.cli_adapter import CLIAdapter
adapter = CLIAdapter("opencode")
cmd = adapter.build_run_command(
agent="dispatch",
session_id="abc123",
prompt="Start the pipeline"
)
"""
from __future__ import annotations
from dataclasses import dataclass
from pathlib import Path
from typing import ClassVar, Literal
Platform = Literal[
"claude",
"opencode",
"cursor",
"iflow",
"codex",
"kilo",
"kiro",
"gemini",
"antigravity",
"devin",
"qoder",
"codebuddy",
"copilot",
"droid",
"pi",
]
@dataclass
class CLIAdapter:
"""Adapter for different AI coding CLI tools."""
platform: Platform
# =========================================================================
# Agent Name Mapping
# =========================================================================
# OpenCode has built-in agents that cannot be overridden
# See: https://github.com/sst/opencode/issues/4271
# Note: Class-level constant, not a dataclass field
_AGENT_NAME_MAP: ClassVar[dict[Platform, dict[str, str]]] = {
"claude": {}, # No mapping needed
"opencode": {
"plan": "trellis-plan", # 'plan' is built-in in OpenCode
},
}
def get_agent_name(self, agent: str) -> str:
"""Get platform-specific agent name.
Args:
agent: Original agent name (e.g., 'plan', 'dispatch')
Returns:
Platform-specific agent name (e.g., 'trellis-plan' for OpenCode)
"""
mapping = self._AGENT_NAME_MAP.get(self.platform, {})
return mapping.get(agent, agent)
# =========================================================================
# Agent Path
# =========================================================================
@property
def config_dir_name(self) -> str:
"""Get platform-specific config directory name.
Returns:
Directory name ('.claude', '.opencode', '.cursor', '.iflow', '.codex', '.kilocode', '.kiro', '.gemini', '.agent', '.devin', '.qoder', '.codebuddy', '.github/copilot', '.factory', or '.pi')
"""
if self.platform == "opencode":
return ".opencode"
elif self.platform == "cursor":
return ".cursor"
elif self.platform == "iflow":
return ".iflow"
elif self.platform == "codex":
return ".codex"
elif self.platform == "kilo":
return ".kilocode"
elif self.platform == "kiro":
return ".kiro"
elif self.platform == "gemini":
return ".gemini"
elif self.platform == "antigravity":
return ".agent"
elif self.platform == "devin":
return ".devin"
elif self.platform == "qoder":
return ".qoder"
elif self.platform == "codebuddy":
return ".codebuddy"
elif self.platform == "copilot":
return ".github/copilot"
elif self.platform == "droid":
return ".factory"
elif self.platform == "pi":
return ".pi"
else:
return ".claude"
def get_config_dir(self, project_root: Path) -> Path:
"""Get platform-specific config directory.
Args:
project_root: Project root directory
Returns:
Path to config directory (.claude, .opencode, .cursor, .iflow, .codex, .kilocode, .kiro, .gemini, .agent, .devin, .qoder, .codebuddy, .github/copilot, .factory, or .pi)
"""
return project_root / self.config_dir_name
def get_agent_path(self, agent: str, project_root: Path) -> Path:
"""Get path to agent definition file.
Args:
agent: Agent name (original, before mapping)
project_root: Project root directory
Returns:
Path to agent definition file (.md for most platforms, .toml for Codex)
"""
mapped_name = self.get_agent_name(agent)
if self.platform == "codex":
return self.get_config_dir(project_root) / "agents" / f"{mapped_name}.toml"
return self.get_config_dir(project_root) / "agents" / f"{mapped_name}.md"
def get_commands_path(self, project_root: Path, *parts: str) -> Path:
"""Get path to commands directory or specific command file.
Args:
project_root: Project root directory
*parts: Additional path parts (e.g., 'trellis', 'finish-work.md')
Returns:
Path to commands directory or file
Note:
Cursor uses prefix naming: .cursor/commands/trellis-<name>.md
Antigravity uses workflow directory: .agent/workflows/<name>.md
Devin uses workflow directory: .devin/workflows/trellis-<name>.md
Copilot uses prompt files: .github/prompts/<name>.prompt.md
Pi uses prompt templates: .pi/prompts/trellis-<name>.md
Claude/OpenCode use subdirectory: .claude/commands/trellis/<name>.md
"""
if self.platform == "pi":
prompts_dir = self.get_config_dir(project_root) / "prompts"
if not parts:
return prompts_dir
if len(parts) >= 2 and parts[0] == "trellis":
filename = parts[-1]
if filename.endswith(".md"):
filename = filename[:-3]
return prompts_dir / f"trellis-{filename}.md"
return prompts_dir / Path(*parts)
if self.platform == "devin":
workflow_dir = self.get_config_dir(project_root) / "workflows"
if not parts:
return workflow_dir
if len(parts) >= 2 and parts[0] == "trellis":
filename = parts[-1]
return workflow_dir / f"trellis-{filename}"
return workflow_dir / Path(*parts)
if self.platform in ("antigravity", "kilo"):
workflow_dir = self.get_config_dir(project_root) / "workflows"
if not parts:
return workflow_dir
if len(parts) >= 2 and parts[0] == "trellis":
filename = parts[-1]
return workflow_dir / filename
return workflow_dir / Path(*parts)
if self.platform == "copilot":
prompts_dir = project_root / ".github" / "prompts"
if not parts:
return prompts_dir
if len(parts) >= 2 and parts[0] == "trellis":
filename = parts[-1]
if filename.endswith(".md"):
filename = filename[:-3]
return prompts_dir / f"{filename}.prompt.md"
return prompts_dir / Path(*parts)
if not parts:
return self.get_config_dir(project_root) / "commands"
# Cursor uses prefix naming instead of subdirectory
if self.platform == "cursor" and len(parts) >= 2 and parts[0] == "trellis":
# Convert trellis/<name>.md to trellis-<name>.md
filename = parts[-1]
return (
self.get_config_dir(project_root) / "commands" / f"trellis-{filename}"
)
return self.get_config_dir(project_root) / "commands" / Path(*parts)
def get_trellis_command_path(self, name: str) -> str:
"""Get relative path to a trellis command file.
Args:
name: Command name without extension (e.g., 'finish-work', 'check')
Returns:
Relative path string for use in JSONL entries
Note:
Cursor: .cursor/commands/trellis-<name>.md
Codex: .agents/skills/trellis-<name>/SKILL.md
Kiro: .kiro/skills/trellis-<name>/SKILL.md
Gemini: .gemini/commands/trellis/<name>.toml
Antigravity: .agent/workflows/<name>.md
Devin: .devin/workflows/trellis-<name>.md
Pi: .pi/prompts/trellis-<name>.md
Others: .{platform}/commands/trellis/<name>.md
"""
if self.platform == "cursor":
return f".cursor/commands/trellis-{name}.md"
elif self.platform == "codex":
# 0.5.0-beta.0 renamed all skill dirs to add the `trellis-` prefix
# (see that release's manifest for the 60+ rename entries).
return f".agents/skills/trellis-{name}/SKILL.md"
elif self.platform == "kiro":
return f".kiro/skills/trellis-{name}/SKILL.md"
elif self.platform == "gemini":
return f".gemini/commands/trellis/{name}.toml"
elif self.platform == "antigravity":
return f".agent/workflows/{name}.md"
elif self.platform == "devin":
return f".devin/workflows/trellis-{name}.md"
elif self.platform == "kilo":
return f".kilocode/workflows/{name}.md"
elif self.platform == "copilot":
return f".github/prompts/{name}.prompt.md"
elif self.platform == "droid":
return f".factory/commands/trellis/{name}.md"
elif self.platform == "pi":
return f".pi/prompts/trellis-{name}.md"
else:
return f"{self.config_dir_name}/commands/trellis/{name}.md"
# =========================================================================
# Environment Variables
# =========================================================================
def get_non_interactive_env(self) -> dict[str, str]:
"""Get environment variables for non-interactive mode.
Returns:
Dict of environment variables to set
"""
if self.platform == "opencode":
return {"OPENCODE_NON_INTERACTIVE": "1"}
elif self.platform == "iflow":
return {"IFLOW_NON_INTERACTIVE": "1"}
elif self.platform == "codex":
return {"CODEX_NON_INTERACTIVE": "1"}
elif self.platform == "kiro":
return {"KIRO_NON_INTERACTIVE": "1"}
elif self.platform == "gemini":
return {} # Gemini CLI doesn't have a non-interactive env var
elif self.platform == "antigravity":
return {}
elif self.platform == "devin":
return {}
elif self.platform == "qoder":
return {}
elif self.platform == "codebuddy":
return {}
elif self.platform == "copilot":
return {}
elif self.platform == "droid":
return {}
elif self.platform == "pi":
return {}
else:
return {"CLAUDE_NON_INTERACTIVE": "1"}
# =========================================================================
# CLI Command Building
# =========================================================================
def build_run_command(
self,
agent: str,
prompt: str,
session_id: str | None = None,
skip_permissions: bool = True,
verbose: bool = True,
json_output: bool = True,
) -> list[str]:
"""Build CLI command for running an agent.
Args:
agent: Agent name (will be mapped if needed)
prompt: Prompt to send to the agent
session_id: Optional session ID (Claude Code only for creation)
skip_permissions: Whether to skip permission prompts
verbose: Whether to enable verbose output
json_output: Whether to use JSON output format
Returns:
List of command arguments
"""
mapped_agent = self.get_agent_name(agent)
if self.platform == "opencode":
cmd = ["opencode", "run"]
cmd.extend(["--agent", mapped_agent])
# Note: OpenCode 'run' mode is non-interactive by default
# No equivalent to Claude Code's --dangerously-skip-permissions
# See: https://github.com/anomalyco/opencode/issues/9070
if json_output:
cmd.extend(["--format", "json"])
if verbose:
cmd.extend(["--log-level", "DEBUG", "--print-logs"])
# Note: OpenCode doesn't support --session-id on creation
# Session ID must be extracted from logs after startup
cmd.append(prompt)
elif self.platform == "iflow":
cmd = ["iflow", "-y", "-p"]
cmd.append(f"${mapped_agent} {prompt}")
elif self.platform == "codex":
cmd = ["codex", "exec"]
cmd.append(prompt)
elif self.platform == "kiro":
cmd = ["kiro", "run", prompt]
elif self.platform == "gemini":
cmd = ["gemini"]
cmd.append(prompt)
elif self.platform == "antigravity":
raise ValueError(
"Antigravity workflows are UI slash commands; CLI agent run is not supported."
)
elif self.platform == "devin":
raise ValueError(
"Devin workflows are UI slash commands; CLI agent run is not supported."
)
elif self.platform == "qoder":
cmd = ["qodercli", "-p", prompt]
elif self.platform == "codebuddy":
raise ValueError(
"CodeBuddy does not support non-interactive mode (no CLI agent)"
)
elif self.platform == "copilot":
raise ValueError(
"GitHub Copilot is IDE-only; CLI agent run is not supported."
)
elif self.platform == "droid":
raise ValueError(
"Factory Droid CLI agent run is not yet supported."
)
elif self.platform == "pi":
cmd = ["pi", "-p", prompt]
else: # claude
cmd = ["claude", "-p"]
cmd.extend(["--agent", mapped_agent])
if session_id:
cmd.extend(["--session-id", session_id])
if skip_permissions:
cmd.append("--dangerously-skip-permissions")
if json_output:
cmd.extend(["--output-format", "stream-json"])
if verbose:
cmd.append("--verbose")
cmd.append(prompt)
return cmd
def build_resume_command(self, session_id: str) -> list[str]:
"""Build CLI command for resuming a session.
Args:
session_id: Session ID to resume (ignored for iFlow)
Returns:
List of command arguments
"""
if self.platform == "opencode":
return ["opencode", "run", "--session", session_id]
elif self.platform == "iflow":
# iFlow uses -c to continue most recent conversation
# session_id is ignored as iFlow doesn't support session IDs
return ["iflow", "-c"]
elif self.platform == "codex":
return ["codex", "resume", session_id]
elif self.platform == "kiro":
return ["kiro", "resume", session_id]
elif self.platform == "gemini":
return ["gemini", "--resume", session_id]
elif self.platform == "antigravity":
raise ValueError(
"Antigravity workflows are UI slash commands; CLI resume is not supported."
)
elif self.platform == "devin":
raise ValueError(
"Devin workflows are UI slash commands; CLI resume is not supported."
)
elif self.platform == "qoder":
return ["qodercli", "--resume", session_id]
elif self.platform == "codebuddy":
raise ValueError(
"CodeBuddy does not support non-interactive mode (no CLI agent)"
)
elif self.platform == "copilot":
raise ValueError(
"GitHub Copilot is IDE-only; CLI resume is not supported."
)
elif self.platform == "droid":
raise ValueError(
"Factory Droid CLI resume is not yet supported."
)
elif self.platform == "pi":
return ["pi", "-c", session_id]
else:
return ["claude", "--resume", session_id]
def get_resume_command_str(self, session_id: str, cwd: str | None = None) -> str:
"""Get human-readable resume command string.
Args:
session_id: Session ID to resume
cwd: Optional working directory to cd into
Returns:
Command string for display
"""
cmd = self.build_resume_command(session_id)
cmd_str = " ".join(cmd)
if cwd:
return f"cd {cwd} && {cmd_str}"
return cmd_str
# =========================================================================
# Platform Detection Helpers
# =========================================================================
@property
def is_opencode(self) -> bool:
"""Check if platform is OpenCode."""
return self.platform == "opencode"
@property
def is_claude(self) -> bool:
"""Check if platform is Claude Code."""
return self.platform == "claude"
@property
def is_cursor(self) -> bool:
"""Check if platform is Cursor."""
return self.platform == "cursor"
@property
def is_iflow(self) -> bool:
"""Check if platform is iFlow CLI."""
return self.platform == "iflow"
@property
def cli_name(self) -> str:
"""Get CLI executable name.
Note: Cursor doesn't have a CLI tool, returns None-like value.
"""
if self.is_opencode:
return "opencode"
elif self.is_cursor:
return "cursor" # Note: Cursor is IDE-only, no CLI
elif self.platform == "iflow":
return "iflow"
elif self.platform == "kiro":
return "kiro"
elif self.platform == "gemini":
return "gemini"
elif self.platform == "antigravity":
return "agy"
elif self.platform == "devin":
return "devin"
elif self.platform == "qoder":
return "qodercli"
elif self.platform == "codebuddy":
return "codebuddy"
elif self.platform == "copilot":
return "copilot"
elif self.platform == "droid":
return "droid"
elif self.platform == "pi":
return "pi"
else:
return "claude"
@property
def supports_cli_agents(self) -> bool:
"""Check if platform supports running agents via CLI.
Claude Code, OpenCode, iFlow, and Codex support CLI agent execution.
Cursor is IDE-only and doesn't support CLI agents.
"""
return self.platform in ("claude", "opencode", "iflow", "codex", "pi")
@property
def requires_agent_definition_file(self) -> bool:
"""Check if platform requires an agent definition file (.md/.toml) to run.
Claude Code, OpenCode, iFlow: require agent .md files (--agent flag).
Codex: auto-discovers agents from .codex/agents/*.toml, no --agent flag.
"""
return self.platform in ("claude", "opencode", "iflow")
# =========================================================================
# Session ID Handling
# =========================================================================
@property
def supports_session_id_on_create(self) -> bool:
"""Check if platform supports specifying session ID on creation.
Claude Code: Yes (--session-id)
OpenCode: No (auto-generated, extract from logs)
iFlow: No (no session ID support)
"""
return self.platform == "claude"
def extract_session_id_from_log(self, log_content: str) -> str | None:
"""Extract session ID from log output (OpenCode only).
OpenCode generates session IDs in format: ses_xxx
Args:
log_content: Log file content
Returns:
Session ID if found, None otherwise
"""
import re
# OpenCode session ID pattern
match = re.search(r"ses_[a-zA-Z0-9]+", log_content)
if match:
return match.group(0)
return None
# =============================================================================
# Factory Function
# =============================================================================
def get_cli_adapter(platform: str = "claude") -> CLIAdapter:
"""Get CLI adapter for the specified platform.
Args:
platform: Platform name ('claude', 'opencode', 'cursor', 'iflow', 'codex', 'kilo', 'kiro', 'gemini', 'antigravity', 'devin', 'qoder', 'codebuddy', 'copilot', 'droid', or 'pi')
Returns:
CLIAdapter instance
Raises:
ValueError: If platform is not supported
Note:
'windsurf' is accepted as a deprecated alias for 'devin' (Windsurf was
renamed to Devin) and normalized before validation.
"""
# Deprecated alias: Windsurf was renamed to Devin.
if platform == "windsurf":
platform = "devin"
if platform not in (
"claude",
"opencode",
"cursor",
"iflow",
"codex",
"kilo",
"kiro",
"gemini",
"antigravity",
"devin",
"qoder",
"codebuddy",
"copilot",
"droid",
"pi",
):
raise ValueError(
f"Unsupported platform: {platform} (must be 'claude', 'opencode', 'cursor', 'iflow', 'codex', 'kilo', 'kiro', 'gemini', 'antigravity', 'devin', 'qoder', 'codebuddy', 'copilot', 'droid', or 'pi')"
)
return CLIAdapter(platform=platform) # type: ignore
_ALL_PLATFORM_CONFIG_DIRS = (
".claude",
".cursor",
".iflow",
".opencode",
".codex",
".kilocode",
".kiro",
".gemini",
".agent",
".devin",
".windsurf", # deprecated: pre-rename Devin config dir (still a platform signal)
".qoder",
".codebuddy",
".github/copilot",
".factory",
".pi",
)
"""Platform-specific config directory names used by detect_platform exclusion
checks. `.agents/skills/` is NOT listed here: it is a shared cross-platform
layer (written by Codex, also consumed by Amp/Cline/Warp/etc. via the
agentskills.io standard), not a single-platform signal. Its presence must not
block detection of Kiro, Antigravity, Devin, or other platforms."""
def _has_other_platform_dir(project_root: Path, exclude: set[str]) -> bool:
"""Check if any platform config dir exists besides those in *exclude*."""
return any(
(project_root / d).is_dir()
for d in _ALL_PLATFORM_CONFIG_DIRS
if d not in exclude
)
def detect_platform(project_root: Path) -> Platform:
"""Auto-detect platform based on existing config directories.
Detection order:
1. TRELLIS_PLATFORM environment variable (if set)
2. .opencode directory exists → opencode
3. .iflow directory exists → iflow
4. .cursor directory exists (without .claude) → cursor
5. .codex exists and no other platform dirs → codex
6. .kilocode directory exists → kilo
7. .kiro/skills exists and no other platform dirs → kiro
8. .gemini directory exists → gemini
9. .agent/workflows exists and no other platform dirs → antigravity
10. .devin/workflows (or legacy .windsurf/workflows) exists and no other platform dirs → devin
11. .codebuddy directory exists → codebuddy
12. .qoder directory exists → qoder
13. .pi directory exists → pi
14. Default → claude
Args:
project_root: Project root directory
Returns:
Detected platform ('claude', 'opencode', 'cursor', 'iflow', 'codex', 'kilo', 'kiro', 'gemini', 'antigravity', 'devin', 'qoder', 'codebuddy', 'copilot', 'droid', 'pi', or default 'claude')
"""
import os
# Check environment variable first
env_platform = os.environ.get("TRELLIS_PLATFORM", "").lower()
# Deprecated alias: Windsurf was renamed to Devin.
if env_platform == "windsurf":
env_platform = "devin"
if env_platform in (
"claude",
"opencode",
"cursor",
"iflow",
"codex",
"kilo",
"kiro",
"gemini",
"antigravity",
"devin",
"qoder",
"codebuddy",
"copilot",
"droid",
"pi",
):
return env_platform # type: ignore
# Check for .opencode directory (OpenCode-specific)
if (project_root / ".opencode").is_dir():
return "opencode"
# Check for .iflow directory (iFlow-specific)
if (project_root / ".iflow").is_dir():
return "iflow"
# Check for .cursor directory (Cursor-specific)
# Only detect as cursor if .claude doesn't exist (to avoid confusion)
if (project_root / ".cursor").is_dir() and not (project_root / ".claude").is_dir():
return "cursor"
# Check for .gemini directory (Gemini CLI-specific)
if (project_root / ".gemini").is_dir():
return "gemini"
# Check for .codex directory (Codex-specific)
# .agents/skills/ alone does NOT trigger codex detection (it's a shared standard)
if (project_root / ".codex").is_dir() and not _has_other_platform_dir(
project_root, {".codex", ".agents"}
):
return "codex"
# Check for .kilocode directory (Kilo-specific)
if (project_root / ".kilocode").is_dir():
return "kilo"
# Check for Kiro skills directory only when no other platform config exists
if (project_root / ".kiro" / "skills").is_dir() and not _has_other_platform_dir(
project_root, {".kiro"}
):
return "kiro"
# Check for Antigravity workflow directory only when no other platform config exists
if (
project_root / ".agent" / "workflows"
).is_dir() and not _has_other_platform_dir(
project_root, {".agent", ".gemini"}
):
return "antigravity"
# Check for Devin workflow directory only when no other platform config
# exists. `.windsurf/workflows` is the legacy pre-rename path (still detected
# as devin for back-compat until users migrate via `trellis update --migrate`).
if (
(project_root / ".devin" / "workflows").is_dir()
or (project_root / ".windsurf" / "workflows").is_dir()
) and not _has_other_platform_dir(
project_root, {".devin", ".windsurf"}
):
return "devin"
# Check for .codebuddy directory (CodeBuddy-specific)
if (project_root / ".codebuddy").is_dir():
return "codebuddy"
# Check for .qoder directory (Qoder-specific)
if (project_root / ".qoder").is_dir():
return "qoder"
# Check for .github/copilot directory (GitHub Copilot-specific)
if (project_root / ".github" / "copilot").is_dir():
return "copilot"
# Check for .factory directory (Factory Droid-specific)
if (project_root / ".factory").is_dir():
return "droid"
# Check for .pi directory (Pi Agent-specific)
if (project_root / ".pi").is_dir():
return "pi"
# Fallback: checkout only has the Codex shared-skills layer
# (.agents/skills/trellis-* dirs) and no explicit platform config dir.
# Happens on fresh clones where .codex/ is gitignored/absent but the
# shared skills were committed to git. Must guard against the case
# where .claude/ or any other platform dir also exists — .agents/skills/
# can legitimately coexist with any platform as a shared consumption
# layer for Amp/Cline/Warp/etc.
agents_skills = project_root / ".agents" / "skills"
if agents_skills.is_dir() and not _has_other_platform_dir(
project_root, set()
):
try:
for entry in agents_skills.iterdir():
if entry.is_dir() and entry.name.startswith("trellis-"):
return "codex"
except OSError:
pass
return "claude"
def get_cli_adapter_auto(project_root: Path) -> CLIAdapter:
"""Get CLI adapter with auto-detected platform.
Args:
project_root: Project root directory
Returns:
CLIAdapter instance for detected platform
"""
platform = detect_platform(project_root)
return CLIAdapter(platform=platform)
.trellis/scripts/common/config.py
Executable
+445
View File
@@ -0,0 +1,445 @@
#!/usr/bin/env python3
"""
Trellis configuration reader.
Reads settings from .trellis/config.yaml with sensible defaults.
"""
from __future__ import annotations
import sys
from pathlib import Path
from .paths import DIR_WORKFLOW, get_repo_root
# =============================================================================
# YAML Simple Parser (no dependencies)
# =============================================================================
def _unquote(s: str) -> str:
"""Remove exactly one layer of matching surrounding quotes.
Unlike str.strip('"'), this only removes the outermost pair,
preserving any nested quotes inside the value.
Examples:
_unquote('"hello"') -> 'hello'
_unquote("'hello'") -> 'hello'
_unquote('"echo \\'hi\\'"') -> "echo 'hi'"
_unquote('hello') -> 'hello'
_unquote('"hello\\'') -> '"hello\\'' (mismatched, unchanged)
"""
if len(s) >= 2 and s[0] == s[-1] and s[0] in ('"', "'"):
return s[1:-1]
return s
def _strip_inline_comment(value: str) -> str:
"""Strip ` # …` inline comments while preserving `#` inside quoted strings.
YAML treats ` #` (space-hash) as a comment opener; bare `#` inside a token
is part of the value. Quoted strings are immune.
Mirrors :func:`common.trellis_config._strip_inline_comment` so both
parsers handle ``key: value # comment`` identically.
"""
in_quote: str | None = None
for idx, ch in enumerate(value):
if in_quote:
if ch == in_quote:
in_quote = None
continue
if ch in ('"', "'"):
in_quote = ch
continue
if ch == "#" and (idx == 0 or value[idx - 1].isspace()):
return value[:idx]
return value
def parse_simple_yaml(content: str) -> dict:
"""Parse simple YAML with nested dict support (no dependencies).
Supports:
- key: value (string)
- key: (followed by list items)
- item1
- item2
- key: (followed by nested dict)
nested_key: value
nested_key2:
- item
Uses indentation to detect nesting (2+ spaces deeper = child).
Args:
content: YAML content string.
Returns:
Parsed dict (values can be str, list[str], or dict).
"""
lines = content.splitlines()
result: dict = {}
_parse_yaml_block(lines, 0, 0, result)
return result
def _parse_yaml_block(
lines: list[str], start: int, min_indent: int, target: dict
) -> int:
"""Parse a YAML block into target dict, returning next line index."""
i = start
current_list: list | None = None
while i < len(lines):
line = lines[i]
stripped = line.strip()
# Skip empty lines and comments
if not stripped or stripped.startswith("#"):
i += 1
continue
# Calculate indentation
indent = len(line) - len(line.lstrip())
# If dedented past our block, we're done
if indent < min_indent:
break
if stripped.startswith("- "):
if current_list is not None:
current_list.append(_unquote(stripped[2:].strip()))
i += 1
elif ":" in stripped:
key, _, value = stripped.partition(":")
key = key.strip()
value = _strip_inline_comment(value).strip()
value = _unquote(value)
current_list = None
if value:
# key: value
target[key] = value
i += 1
else:
# key: (no value) — peek ahead to determine list vs nested dict
next_i, next_line = _next_content_line(lines, i + 1)
if next_i >= len(lines):
target[key] = {}
i = next_i
elif next_line.strip().startswith("- "):
# It's a list
current_list = []
target[key] = current_list
i += 1
else:
next_indent = len(next_line) - len(next_line.lstrip())
if next_indent > indent:
# It's a nested dict
nested: dict = {}
target[key] = nested
i = _parse_yaml_block(lines, i + 1, next_indent, nested)
else:
# Empty value, same or less indent follows
target[key] = {}
i += 1
else:
i += 1
return i
def _next_content_line(lines: list[str], start: int) -> tuple[int, str]:
"""Find the next non-empty, non-comment line."""
i = start
while i < len(lines):
stripped = lines[i].strip()
if stripped and not stripped.startswith("#"):
return i, lines[i]
i += 1
return i, ""
# Defaults
DEFAULT_SESSION_COMMIT_MESSAGE = "chore: record journal"
DEFAULT_MAX_JOURNAL_LINES = 2000
DEFAULT_SESSION_AUTO_COMMIT = True
CONFIG_FILE = "config.yaml"
def _is_true_config_value(value: object) -> bool:
"""Return True when a config value represents an enabled flag."""
if isinstance(value, bool):
return value
if isinstance(value, str):
return value.strip().lower() == "true"
return False
def _get_config_path(repo_root: Path | None = None) -> Path:
"""Get path to config.yaml."""
root = repo_root or get_repo_root()
return root / DIR_WORKFLOW / CONFIG_FILE
def _load_config(repo_root: Path | None = None) -> dict:
"""Load and parse config.yaml. Returns empty dict on any error."""
config_file = _get_config_path(repo_root)
try:
content = config_file.read_text(encoding="utf-8")
return parse_simple_yaml(content)
except (OSError, IOError):
return {}
def get_session_commit_message(repo_root: Path | None = None) -> str:
"""Get the commit message for auto-committing session records."""
config = _load_config(repo_root)
return config.get("session_commit_message", DEFAULT_SESSION_COMMIT_MESSAGE)
def get_max_journal_lines(repo_root: Path | None = None) -> int:
"""Get the maximum lines per journal file."""
config = _load_config(repo_root)
value = config.get("max_journal_lines", DEFAULT_MAX_JOURNAL_LINES)
try:
return int(value)
except (ValueError, TypeError):
return DEFAULT_MAX_JOURNAL_LINES
def get_session_auto_commit(repo_root: Path | None = None) -> bool:
"""Whether scripts should auto-stage + auto-commit session/task changes.
Governs both ``add_session.py:_auto_commit_workspace`` and
``task_store.py:_auto_commit_archive``.
Default: ``True`` (existing behavior — auto-stage + auto-commit).
Set ``session_auto_commit: false`` in ``.trellis/config.yaml`` to skip
auto-staging entirely; the journal/archive files are still written to
disk, but the user manages ``git add`` / ``git commit`` themselves.
Accepts native YAML booleans (``true`` / ``false``) and the string
aliases ``true / false / yes / no / 1 / 0 / on / off`` (case-insensitive).
Invalid values fall back to ``True`` with a stderr warning.
"""
config = _load_config(repo_root)
raw = config.get("session_auto_commit", DEFAULT_SESSION_AUTO_COMMIT)
if isinstance(raw, bool):
return raw
s = str(raw).strip().lower()
if s in ("true", "yes", "1", "on"):
return True
if s in ("false", "no", "0", "off"):
return False
print(
f"[WARN] invalid session_auto_commit value: {raw!r}; using true (default)",
file=sys.stderr,
)
return DEFAULT_SESSION_AUTO_COMMIT
def get_hooks(event: str, repo_root: Path | None = None) -> list[str]:
"""Get hook commands for a lifecycle event.
Args:
event: Event name (e.g. "after_create", "after_archive").
repo_root: Repository root path.
Returns:
List of shell commands to execute, empty if none configured.
"""
config = _load_config(repo_root)
hooks = config.get("hooks")
if not isinstance(hooks, dict):
return []
commands = hooks.get(event)
if isinstance(commands, list):
return [str(c) for c in commands]
return []
# =============================================================================
# Monorepo / Packages
# =============================================================================
def get_packages(repo_root: Path | None = None) -> dict[str, dict] | None:
"""Get monorepo package declarations.
Returns:
Dict mapping package name to its config (path, type, etc.),
or None if not configured (single-repo mode).
Example return:
{"cli": {"path": "packages/cli"}, "docs-site": {"path": "docs-site", "type": "submodule"}}
"""
config = _load_config(repo_root)
packages = config.get("packages")
if not isinstance(packages, dict):
return None
# Ensure each value is a dict (filter out scalar entries)
filtered = {k: v for k, v in packages.items() if isinstance(v, dict)}
if not filtered:
return None
return filtered
def get_default_package(repo_root: Path | None = None) -> str | None:
"""Get the default package name from config.
Returns:
Package name string, or None if not configured.
"""
config = _load_config(repo_root)
value = config.get("default_package")
return str(value) if value else None
def get_submodule_packages(repo_root: Path | None = None) -> dict[str, str]:
"""Get packages that are git submodules.
Returns:
Dict mapping package name to its path for submodule-type packages.
Empty dict if none configured.
Example return:
{"docs-site": "docs-site"}
"""
packages = get_packages(repo_root)
if packages is None:
return {}
return {
name: cfg.get("path", name)
for name, cfg in packages.items()
if cfg.get("type") == "submodule"
}
def get_git_packages(repo_root: Path | None = None) -> dict[str, str]:
"""Get packages that have their own independent git repository.
These are sub-directories with their own .git (not submodules),
marked with ``git: true`` in config.yaml.
Returns:
Dict mapping package name to its path for git-repo packages.
Empty dict if none configured.
Example config::
packages:
backend:
path: iqs
git: true
Example return::
{"backend": "iqs"}
"""
packages = get_packages(repo_root)
if packages is None:
return {}
return {
name: cfg.get("path", name)
for name, cfg in packages.items()
if _is_true_config_value(cfg.get("git"))
}
def is_monorepo(repo_root: Path | None = None) -> bool:
"""Check if the project is configured as a monorepo (has packages in config)."""
return get_packages(repo_root) is not None
def get_spec_base(package: str | None = None, repo_root: Path | None = None) -> str:
"""Get the spec directory base path relative to .trellis/.
Single-repo: returns "spec"
Monorepo with package: returns "spec/<package>"
Monorepo without package: returns "spec" (caller should specify package)
"""
if package and is_monorepo(repo_root):
return f"spec/{package}"
return "spec"
def validate_package(package: str, repo_root: Path | None = None) -> bool:
"""Check if a package name is valid in this project.
Single-repo (no packages configured): always returns True.
Monorepo: returns True only if package exists in config.yaml packages.
"""
packages = get_packages(repo_root)
if packages is None:
return True # Single-repo, no validation needed
return package in packages
def resolve_package(
task_package: str | None = None,
repo_root: Path | None = None,
) -> str | None:
"""Resolve package from inferred sources with validation.
Checks in order: task_package → default_package.
Invalid inferred values print a warning to stderr and are skipped.
Returns:
Resolved package name, or None if no valid package found.
Note:
CLI --package should be validated separately by the caller
(fail-fast with available packages list on error).
"""
packages = get_packages(repo_root)
if packages is None:
return None # Single-repo, no package needed
# Try task_package (guard against non-string values from malformed JSON)
if task_package and isinstance(task_package, str):
if task_package in packages:
return task_package
print(
f"Warning: task.json package '{task_package}' not found in config, skipping",
file=sys.stderr,
)
# Try default_package
default = get_default_package(repo_root)
if default:
if default in packages:
return default
print(
f"Warning: default_package '{default}' not found in config, skipping",
file=sys.stderr,
)
return None
def get_spec_scope(repo_root: Path | None = None) -> list[str] | str | None:
"""Get session.spec_scope configuration.
Returns:
list[str]: Package names to include in spec scanning.
str: "active_task" to use current task's package.
None: No scope configured (scan all packages).
"""
config = _load_config(repo_root)
session = config.get("session")
if not isinstance(session, dict):
return None
scope = session.get("spec_scope")
if scope is None:
return None
if isinstance(scope, str):
return scope # e.g. "active_task"
if isinstance(scope, list):
return [str(s) for s in scope]
return None
.trellis/scripts/common/developer.py
Executable
+190
View File
@@ -0,0 +1,190 @@
#!/usr/bin/env python3
"""
Developer management utilities.
Provides:
init_developer - Initialize developer
ensure_developer - Ensure developer is initialized (exit if not)
show_developer_info - Show developer information
"""
from __future__ import annotations
import sys
from datetime import datetime
from pathlib import Path
from .paths import (
DIR_WORKFLOW,
DIR_WORKSPACE,
DIR_TASKS,
FILE_DEVELOPER,
FILE_JOURNAL_PREFIX,
get_repo_root,
get_developer,
check_developer,
)
# =============================================================================
# Developer Initialization
# =============================================================================
def init_developer(name: str, repo_root: Path | None = None) -> bool:
"""Initialize developer.
Creates:
- .trellis/.developer file with developer info
- .trellis/workspace/<name>/ directory structure
- Initial journal file and index.md
Args:
name: Developer name.
repo_root: Repository root path. Defaults to auto-detected.
Returns:
True on success, False on error.
"""
if not name:
print("Error: developer name is required", file=sys.stderr)
return False
if repo_root is None:
repo_root = get_repo_root()
dev_file = repo_root / DIR_WORKFLOW / FILE_DEVELOPER
workspace_dir = repo_root / DIR_WORKFLOW / DIR_WORKSPACE / name
# Create .developer file
initialized_at = datetime.now().isoformat()
try:
dev_file.write_text(
f"name={name}\ninitialized_at={initialized_at}\n",
encoding="utf-8"
)
except (OSError, IOError) as e:
print(f"Error: Failed to create .developer file: {e}", file=sys.stderr)
return False
# Create workspace directory structure
try:
workspace_dir.mkdir(parents=True, exist_ok=True)
except (OSError, IOError) as e:
print(f"Error: Failed to create workspace directory: {e}", file=sys.stderr)
return False
# Create initial journal file
journal_file = workspace_dir / f"{FILE_JOURNAL_PREFIX}1.md"
if not journal_file.exists():
today = datetime.now().strftime("%Y-%m-%d")
journal_content = f"""# Journal - {name} (Part 1)
> AI development session journal
> Started: {today}
---
"""
try:
journal_file.write_text(journal_content, encoding="utf-8")
except (OSError, IOError) as e:
print(f"Error: Failed to create journal file: {e}", file=sys.stderr)
return False
# Create index.md with markers for auto-update
index_file = workspace_dir / "index.md"
if not index_file.exists():
index_content = f"""# Workspace Index - {name}
> Journal tracking for AI development sessions.
---
## Current Status
<!-- @@@auto:current-status -->
- **Active File**: `journal-1.md`
- **Total Sessions**: 0
- **Last Active**: -
<!-- @@@/auto:current-status -->
---
## Active Documents
<!-- @@@auto:active-documents -->
| File | Lines | Status |
|------|-------|--------|
| `journal-1.md` | ~0 | Active |
<!-- @@@/auto:active-documents -->
---
## Session History
<!-- @@@auto:session-history -->
| # | Date | Title | Commits | Branch |
|---|------|-------|---------|--------|
<!-- @@@/auto:session-history -->
---
## Notes
- Sessions are appended to journal files
- New journal file created when current exceeds 2000 lines
- Use `add_session.py` to record sessions
"""
try:
index_file.write_text(index_content, encoding="utf-8")
except (OSError, IOError) as e:
print(f"Error: Failed to create index.md: {e}", file=sys.stderr)
return False
print(f"Developer initialized: {name}")
print(f" .developer file: {dev_file}")
print(f" Workspace dir: {workspace_dir}")
return True
def ensure_developer(repo_root: Path | None = None) -> None:
"""Ensure developer is initialized, exit if not.
Args:
repo_root: Repository root path. Defaults to auto-detected.
"""
if repo_root is None:
repo_root = get_repo_root()
if not check_developer(repo_root):
print("Error: Developer not initialized.", file=sys.stderr)
print(f"Run: python3 ./{DIR_WORKFLOW}/scripts/init_developer.py <your-name>", file=sys.stderr)
sys.exit(1)
def show_developer_info(repo_root: Path | None = None) -> None:
"""Show developer information.
Args:
repo_root: Repository root path. Defaults to auto-detected.
"""
if repo_root is None:
repo_root = get_repo_root()
developer = get_developer(repo_root)
if not developer:
print("Developer: (not initialized)")
else:
print(f"Developer: {developer}")
print(f"Workspace: {DIR_WORKFLOW}/{DIR_WORKSPACE}/{developer}/")
print(f"Tasks: {DIR_WORKFLOW}/{DIR_TASKS}/")
# =============================================================================
# Main Entry (for testing)
# =============================================================================
if __name__ == "__main__":
show_developer_info()
.trellis/scripts/common/git.py
Executable
+31
View File
@@ -0,0 +1,31 @@
"""
Git command execution utility.
Single source of truth for running git commands across all Trellis scripts.
"""
from __future__ import annotations
import subprocess
from pathlib import Path
def run_git(args: list[str], cwd: Path | None = None) -> tuple[int, str, str]:
"""Run a git command and return (returncode, stdout, stderr).
Uses UTF-8 encoding with -c i18n.logOutputEncoding=UTF-8 to ensure
consistent output across all platforms (Windows, macOS, Linux).
"""
try:
git_args = ["git", "-c", "i18n.logOutputEncoding=UTF-8"] + args
result = subprocess.run(
git_args,
cwd=cwd,
capture_output=True,
text=True,
encoding="utf-8",
errors="replace",
)
return result.returncode, result.stdout, result.stderr
except Exception as e:
return 1, "", str(e)
.trellis/scripts/common/git_context.py
Executable
+106
View File
@@ -0,0 +1,106 @@
#!/usr/bin/env python3
# -*- coding: utf-8 -*-
"""
Git and Session Context utilities.
Entry shim — delegates to session_context and packages_context.
Provides:
output_json - Output context in JSON format
output_text - Output context in text format
"""
from __future__ import annotations
import json
from .git import run_git
from .session_context import (
get_context_json,
get_context_text,
get_context_record_json,
get_context_text_record,
output_json,
output_text,
)
from .packages_context import (
get_context_packages_text,
get_context_packages_json,
)
from .trellis_config import read_trellis_config
from .workflow_phase import (
filter_platform,
get_phase_index,
get_step,
resolve_effective_platform,
)
# Backward-compatible alias — external modules import this name
_run_git_command = run_git
# =============================================================================
# Main Entry
# =============================================================================
def main() -> None:
"""CLI entry point."""
import argparse
parser = argparse.ArgumentParser(description="Get Session Context for AI Agent")
parser.add_argument(
"--json",
"-j",
action="store_true",
help="Output in JSON format (works with any --mode)",
)
parser.add_argument(
"--mode",
"-m",
choices=["default", "record", "packages", "phase"],
default="default",
help="Output mode: default (full context), record (for record-session), packages (package info only), phase (workflow step extraction)",
)
parser.add_argument(
"--step",
help="Step id for --mode phase, e.g. 1.1, 2.2. Omit to get the Phase Index.",
)
parser.add_argument(
"--platform",
help="Platform name for --mode phase, e.g. cursor, claude-code. Filters platform-tagged blocks.",
)
args = parser.parse_args()
if args.mode == "record":
if args.json:
print(json.dumps(get_context_record_json(), indent=2, ensure_ascii=False))
else:
print(get_context_text_record())
elif args.mode == "packages":
if args.json:
print(json.dumps(get_context_packages_json(), indent=2, ensure_ascii=False))
else:
print(get_context_packages_text())
elif args.mode == "phase":
content = get_step(args.step) if args.step else get_phase_index()
if not content.strip():
if args.step:
parser.exit(2, f"Step not found: {args.step}\n")
else:
parser.exit(2, "Phase Index section not found in workflow.md\n")
if args.platform:
effective = resolve_effective_platform(
args.platform, read_trellis_config()
)
content = filter_platform(content, effective)
print(content, end="")
else:
if args.json:
output_json()
else:
output_text()
if __name__ == "__main__":
main()
.trellis/scripts/common/io.py
Executable
+37
View File
@@ -0,0 +1,37 @@
"""
JSON file I/O utilities.
Provides read_json and write_json as the single source of truth
for JSON file operations across all Trellis scripts.
"""
from __future__ import annotations
import json
from pathlib import Path
def read_json(path: Path) -> dict | None:
"""Read and parse a JSON file.
Returns None if the file doesn't exist, is invalid JSON, or can't be read.
"""
try:
return json.loads(path.read_text(encoding="utf-8"))
except (FileNotFoundError, json.JSONDecodeError, OSError):
return None
def write_json(path: Path, data: dict) -> bool:
"""Write dict to JSON file with pretty formatting.
Returns True on success, False on error.
"""
try:
path.write_text(
json.dumps(data, indent=2, ensure_ascii=False),
encoding="utf-8",
)
return True
except (OSError, IOError):
return False
.trellis/scripts/common/log.py
Executable
+45
View File
@@ -0,0 +1,45 @@
"""
Terminal output utilities: colors and structured logging.
Single source of truth for Colors and log_* functions
used across all Trellis scripts.
"""
from __future__ import annotations
class Colors:
"""ANSI color codes for terminal output."""
RED = "\033[0;31m"
GREEN = "\033[0;32m"
YELLOW = "\033[1;33m"
BLUE = "\033[0;34m"
CYAN = "\033[0;36m"
DIM = "\033[2m"
NC = "\033[0m" # No Color / Reset
def colored(text: str, color: str) -> str:
"""Apply ANSI color to text."""
return f"{color}{text}{Colors.NC}"
def log_info(msg: str) -> None:
"""Print info-level message with [INFO] prefix."""
print(f"{Colors.BLUE}[INFO]{Colors.NC} {msg}")
def log_success(msg: str) -> None:
"""Print success message with [SUCCESS] prefix."""
print(f"{Colors.GREEN}[SUCCESS]{Colors.NC} {msg}")
def log_warn(msg: str) -> None:
"""Print warning message with [WARN] prefix."""
print(f"{Colors.YELLOW}[WARN]{Colors.NC} {msg}")
def log_error(msg: str) -> None:
"""Print error message with [ERROR] prefix."""
print(f"{Colors.RED}[ERROR]{Colors.NC} {msg}")
.trellis/scripts/common/packages_context.py
Executable
+238
View File
@@ -0,0 +1,238 @@
#!/usr/bin/env python3
"""
Package discovery and context output.
Provides:
get_packages_info - Get structured package info
get_packages_section - Build PACKAGES text section
get_context_packages_text - Full packages text output (--mode packages)
get_context_packages_json - Full packages JSON output (--mode packages --json)
"""
from __future__ import annotations
from pathlib import Path
from .config import _is_true_config_value, get_default_package, get_packages, get_spec_scope
from .paths import (
DIR_SPEC,
DIR_WORKFLOW,
get_current_task,
get_repo_root,
)
from .tasks import load_task
# =============================================================================
# Internal Helpers
# =============================================================================
def _scan_spec_layers(spec_dir: Path, package: str | None = None) -> list[str]:
"""Scan spec directory for available layers (subdirectories).
For monorepo: scans spec/<package>/
For single-repo: scans spec/
"""
target = spec_dir / package if package else spec_dir
if not target.is_dir():
return []
return sorted(
d.name for d in target.iterdir() if d.is_dir() and d.name != "guides"
)
def _get_active_task_package(repo_root: Path) -> str | None:
"""Get the package field from the active task's task.json."""
current = get_current_task(repo_root)
if not current:
return None
ct = load_task(repo_root / current)
return ct.package if ct and ct.package else None
def _resolve_scope_set(
packages: dict,
spec_scope,
task_pkg: str | None,
default_pkg: str | None,
) -> set | None:
"""Resolve spec_scope to a set of allowed package names, or None for full scan."""
if not packages:
return None
if spec_scope is None:
return None
if isinstance(spec_scope, str) and spec_scope == "active_task":
if task_pkg and task_pkg in packages:
return {task_pkg}
if default_pkg and default_pkg in packages:
return {default_pkg}
return None
if isinstance(spec_scope, list):
valid = {e for e in spec_scope if e in packages}
if valid:
return valid
# All invalid: fallback
if task_pkg and task_pkg in packages:
return {task_pkg}
if default_pkg and default_pkg in packages:
return {default_pkg}
return None
return None
# =============================================================================
# Public Functions
# =============================================================================
def get_packages_info(repo_root: Path) -> list[dict]:
"""Get structured package info for monorepo projects.
Returns list of dicts with keys: name, path, type, default, specLayers,
isSubmodule, isGitRepo.
Returns empty list for single-repo projects.
"""
packages = get_packages(repo_root)
if not packages:
return []
default_pkg = get_default_package(repo_root)
spec_dir = repo_root / DIR_WORKFLOW / DIR_SPEC
result = []
for pkg_name, pkg_config in packages.items():
pkg_path = pkg_config.get("path", pkg_name) if isinstance(pkg_config, dict) else str(pkg_config)
pkg_type = pkg_config.get("type", "local") if isinstance(pkg_config, dict) else "local"
pkg_git = pkg_config.get("git", False) if isinstance(pkg_config, dict) else False
layers = _scan_spec_layers(spec_dir, pkg_name)
result.append({
"name": pkg_name,
"path": pkg_path,
"type": pkg_type,
"default": pkg_name == default_pkg,
"specLayers": layers,
"isSubmodule": pkg_type == "submodule",
"isGitRepo": _is_true_config_value(pkg_git),
})
return result
def get_packages_section(repo_root: Path) -> str:
"""Build the PACKAGES section for text output."""
spec_dir = repo_root / DIR_WORKFLOW / DIR_SPEC
pkg_info = get_packages_info(repo_root)
lines: list[str] = []
lines.append("## PACKAGES")
if not pkg_info:
lines.append("(single-repo mode)")
layers = _scan_spec_layers(spec_dir)
if layers:
lines.append(f"Spec layers: {', '.join(layers)}")
return "\n".join(lines)
default_pkg = get_default_package(repo_root)
for pkg in pkg_info:
layers_str = f" [{', '.join(pkg['specLayers'])}]" if pkg["specLayers"] else ""
submodule_tag = " (submodule)" if pkg["isSubmodule"] else ""
git_repo_tag = " (git repo)" if pkg["isGitRepo"] else ""
default_tag = " *" if pkg["default"] else ""
lines.append(
f"- {pkg['name']:<16} {pkg['path']:<20}{layers_str}{submodule_tag}{git_repo_tag}{default_tag}"
)
if default_pkg:
lines.append(f"Default package: {default_pkg}")
return "\n".join(lines)
def get_context_packages_text(repo_root: Path | None = None) -> str:
"""Get packages context as formatted text (for --mode packages)."""
if repo_root is None:
repo_root = get_repo_root()
pkg_info = get_packages_info(repo_root)
lines: list[str] = []
if not pkg_info:
spec_dir = repo_root / DIR_WORKFLOW / DIR_SPEC
lines.append("Single-repo project (no packages configured)")
lines.append("")
layers = _scan_spec_layers(spec_dir)
if layers:
lines.append(f"Spec layers: {', '.join(layers)}")
return "\n".join(lines)
# Resolve scope for annotations
packages_dict = get_packages(repo_root) or {}
default_pkg = get_default_package(repo_root)
spec_scope = get_spec_scope(repo_root)
task_pkg = _get_active_task_package(repo_root)
scope_set = _resolve_scope_set(packages_dict, spec_scope, task_pkg, default_pkg)
lines.append("## PACKAGES")
lines.append("")
for pkg in pkg_info:
default_tag = " (default)" if pkg["default"] else ""
type_tag = f" [{pkg['type']}]" if pkg["type"] != "local" else ""
git_tag = " [git repo]" if pkg["isGitRepo"] else ""
# Scope annotation
scope_tag = ""
if scope_set is not None and pkg["name"] not in scope_set:
scope_tag = " (out of scope)"
lines.append(f"### {pkg['name']}{default_tag}{type_tag}{git_tag}{scope_tag}")
lines.append(f"Path: {pkg['path']}")
if pkg["specLayers"]:
lines.append(f"Spec layers: {', '.join(pkg['specLayers'])}")
for layer in pkg["specLayers"]:
lines.append(f" - .trellis/spec/{pkg['name']}/{layer}/index.md")
else:
lines.append("Spec: not configured")
lines.append("")
# Also show shared guides
guides_dir = repo_root / DIR_WORKFLOW / DIR_SPEC / "guides"
if guides_dir.is_dir():
lines.append("### Shared Guides (always included)")
lines.append("Path: .trellis/spec/guides/index.md")
lines.append("")
return "\n".join(lines)
def get_context_packages_json(repo_root: Path | None = None) -> dict:
"""Get packages context as a dictionary (for --mode packages --json)."""
if repo_root is None:
repo_root = get_repo_root()
pkg_info = get_packages_info(repo_root)
if not pkg_info:
spec_dir = repo_root / DIR_WORKFLOW / DIR_SPEC
layers = _scan_spec_layers(spec_dir)
return {
"mode": "single-repo",
"specLayers": layers,
}
default_pkg = get_default_package(repo_root)
spec_scope = get_spec_scope(repo_root)
task_pkg = _get_active_task_package(repo_root)
return {
"mode": "monorepo",
"packages": pkg_info,
"defaultPackage": default_pkg,
"specScope": spec_scope,
"activeTaskPackage": task_pkg,
}
.trellis/scripts/common/paths.py
Executable
+447
View File
@@ -0,0 +1,447 @@
#!/usr/bin/env python3
"""
Common path utilities for Trellis workflow.
Provides:
get_repo_root - Get repository root directory
get_developer - Get developer name
get_workspace_dir - Get developer workspace directory
get_tasks_dir - Get tasks directory
get_active_journal_file - Get current journal file
"""
from __future__ import annotations
import re
from datetime import datetime
from pathlib import Path
# =============================================================================
# Path Constants (change here to rename directories)
# =============================================================================
# Directory names
DIR_WORKFLOW = ".trellis"
DIR_WORKSPACE = "workspace"
DIR_TASKS = "tasks"
DIR_ARCHIVE = "archive"
DIR_SPEC = "spec"
DIR_SCRIPTS = "scripts"
# File names
FILE_DEVELOPER = ".developer"
FILE_CURRENT_TASK = ".current-task"
FILE_TASK_JSON = "task.json"
FILE_JOURNAL_PREFIX = "journal-"
# =============================================================================
# Repository Root
# =============================================================================
def get_repo_root(start_path: Path | None = None) -> Path:
"""Find the nearest directory containing .trellis/ folder.
This handles nested git repos correctly (e.g., test project inside another repo).
Args:
start_path: Starting directory to search from. Defaults to current directory.
Returns:
Path to repository root, or current directory if no .trellis/ found.
"""
current = (start_path or Path.cwd()).resolve()
while current != current.parent:
if (current / DIR_WORKFLOW).is_dir():
return current
current = current.parent
# Fallback to current directory if no .trellis/ found
return Path.cwd().resolve()
# =============================================================================
# Developer
# =============================================================================
def get_developer(repo_root: Path | None = None) -> str | None:
"""Get developer name from .developer file.
Args:
repo_root: Repository root path. Defaults to auto-detected.
Returns:
Developer name or None if not initialized.
"""
if repo_root is None:
repo_root = get_repo_root()
dev_file = repo_root / DIR_WORKFLOW / FILE_DEVELOPER
if not dev_file.is_file():
return None
try:
content = dev_file.read_text(encoding="utf-8")
for line in content.splitlines():
if line.startswith("name="):
return line.split("=", 1)[1].strip()
except (OSError, IOError):
pass
return None
def check_developer(repo_root: Path | None = None) -> bool:
"""Check if developer is initialized.
Args:
repo_root: Repository root path. Defaults to auto-detected.
Returns:
True if developer is initialized.
"""
return get_developer(repo_root) is not None
# =============================================================================
# Tasks Directory
# =============================================================================
def get_tasks_dir(repo_root: Path | None = None) -> Path:
"""Get tasks directory path.
Args:
repo_root: Repository root path. Defaults to auto-detected.
Returns:
Path to tasks directory.
"""
if repo_root is None:
repo_root = get_repo_root()
return repo_root / DIR_WORKFLOW / DIR_TASKS
# =============================================================================
# Workspace Directory
# =============================================================================
def get_workspace_dir(repo_root: Path | None = None) -> Path | None:
"""Get developer workspace directory.
Args:
repo_root: Repository root path. Defaults to auto-detected.
Returns:
Path to workspace directory or None if developer not set.
"""
if repo_root is None:
repo_root = get_repo_root()
developer = get_developer(repo_root)
if developer:
return repo_root / DIR_WORKFLOW / DIR_WORKSPACE / developer
return None
# =============================================================================
# Journal File
# =============================================================================
def get_active_journal_file(repo_root: Path | None = None) -> Path | None:
"""Get the current active journal file.
Args:
repo_root: Repository root path. Defaults to auto-detected.
Returns:
Path to active journal file or None if not found.
"""
if repo_root is None:
repo_root = get_repo_root()
workspace_dir = get_workspace_dir(repo_root)
if workspace_dir is None or not workspace_dir.is_dir():
return None
latest: Path | None = None
highest = 0
for f in workspace_dir.glob(f"{FILE_JOURNAL_PREFIX}*.md"):
if not f.is_file():
continue
# Extract number from filename
name = f.stem # e.g., "journal-1"
match = re.search(r"(\d+)$", name)
if match:
num = int(match.group(1))
if num > highest:
highest = num
latest = f
return latest
def count_lines(file_path: Path) -> int:
"""Count lines in a file.
Args:
file_path: Path to file.
Returns:
Number of lines, or 0 if file doesn't exist.
"""
if not file_path.is_file():
return 0
try:
return len(file_path.read_text(encoding="utf-8").splitlines())
except (OSError, IOError):
return 0
# =============================================================================
# Current Task Management
# =============================================================================
def normalize_task_ref(task_ref: str) -> str:
"""Normalize a task ref for stable runtime storage.
Stored refs should prefer repo-relative POSIX paths like
`.trellis/tasks/03-27-my-task`, even on Windows. Absolute paths are preserved
unless they can later be converted back to repo-relative form by callers.
"""
normalized = task_ref.strip()
if not normalized:
return ""
path_obj = Path(normalized)
if path_obj.is_absolute():
return str(path_obj)
normalized = normalized.replace("\\", "/")
while normalized.startswith("./"):
normalized = normalized[2:]
if normalized.startswith(f"{DIR_TASKS}/"):
return f"{DIR_WORKFLOW}/{normalized}"
return normalized
def resolve_task_ref(task_ref: str, repo_root: Path | None = None) -> Path | None:
"""Resolve a task ref to an absolute task directory path."""
if repo_root is None:
repo_root = get_repo_root()
normalized = normalize_task_ref(task_ref)
if not normalized:
return None
path_obj = Path(normalized)
if path_obj.is_absolute():
return path_obj
if normalized.startswith(f"{DIR_WORKFLOW}/"):
return repo_root / path_obj
return repo_root / DIR_WORKFLOW / DIR_TASKS / path_obj
def get_current_task(
repo_root: Path | None = None,
platform_input: dict | None = None,
platform: str | None = None,
) -> str | None:
"""Get current task directory path (relative to repo_root).
Args:
repo_root: Repository root path. Defaults to auto-detected.
Returns:
Relative path to current task directory or None.
"""
if repo_root is None:
repo_root = get_repo_root()
from .active_task import resolve_active_task
return resolve_active_task(repo_root, platform_input, platform).task_path
def get_current_task_abs(
repo_root: Path | None = None,
platform_input: dict | None = None,
platform: str | None = None,
) -> Path | None:
"""Get current task directory absolute path.
Args:
repo_root: Repository root path. Defaults to auto-detected.
Returns:
Absolute path to current task directory or None.
"""
if repo_root is None:
repo_root = get_repo_root()
relative = get_current_task(repo_root, platform_input, platform)
if relative:
return resolve_task_ref(relative, repo_root)
return None
def get_current_task_source(
repo_root: Path | None = None,
platform_input: dict | None = None,
platform: str | None = None,
) -> tuple[str, str | None, str | None]:
"""Get active task source as (`source`, `context_key`, `task_path`)."""
if repo_root is None:
repo_root = get_repo_root()
from .active_task import get_current_task_source as _get_source
return _get_source(repo_root, platform_input, platform)
def set_current_task(
task_path: str,
repo_root: Path | None = None,
platform_input: dict | None = None,
platform: str | None = None,
) -> bool:
"""Set current task in session scope.
Args:
task_path: Task directory path (relative to repo_root).
repo_root: Repository root path. Defaults to auto-detected.
Returns:
True on success, False on error.
"""
if repo_root is None:
repo_root = get_repo_root()
from .active_task import set_active_task
return set_active_task(
task_path,
repo_root,
platform_input=platform_input,
platform=platform,
) is not None
def clear_current_task(
repo_root: Path | None = None,
platform_input: dict | None = None,
platform: str | None = None,
) -> bool:
"""Clear current task in session scope.
Args:
repo_root: Repository root path. Defaults to auto-detected.
Returns:
True on success.
"""
if repo_root is None:
repo_root = get_repo_root()
from .active_task import clear_active_task
clear_active_task(
repo_root,
platform_input=platform_input,
platform=platform,
)
return True
def has_current_task(repo_root: Path | None = None) -> bool:
"""Check if has current task.
Args:
repo_root: Repository root path. Defaults to auto-detected.
Returns:
True if current task is set.
"""
return get_current_task(repo_root) is not None
# =============================================================================
# Task ID Generation
# =============================================================================
def generate_task_date_prefix() -> str:
"""Generate task ID based on date (MM-DD format).
Returns:
Date prefix string (e.g., "01-21").
"""
return datetime.now().strftime("%m-%d")
# =============================================================================
# Monorepo / Package Paths
# =============================================================================
def get_spec_dir(package: str | None = None, repo_root: Path | None = None) -> Path:
"""Get the spec directory path.
Single-repo: .trellis/spec
Monorepo with package: .trellis/spec/<package>
Uses lazy import to avoid circular dependency with config.py.
"""
if repo_root is None:
repo_root = get_repo_root()
from .config import get_spec_base
base = get_spec_base(package, repo_root)
return repo_root / DIR_WORKFLOW / base
def get_package_path(package: str, repo_root: Path | None = None) -> Path | None:
"""Get a package's source directory absolute path from config.
Returns:
Absolute path to the package directory, or None if not found.
"""
if repo_root is None:
repo_root = get_repo_root()
from .config import get_packages
packages = get_packages(repo_root)
if not packages or package not in packages:
return None
info = packages[package]
if isinstance(info, dict):
rel_path = info.get("path", package)
else:
rel_path = str(info)
return repo_root / rel_path
# =============================================================================
# Main Entry (for testing)
# =============================================================================
if __name__ == "__main__":
repo = get_repo_root()
print(f"Repository root: {repo}")
print(f"Developer: {get_developer(repo)}")
print(f"Tasks dir: {get_tasks_dir(repo)}")
print(f"Workspace dir: {get_workspace_dir(repo)}")
print(f"Journal file: {get_active_journal_file(repo)}")
print(f"Current task: {get_current_task(repo)}")
.trellis/scripts/common/safe_commit.py
Executable
+315
View File
@@ -0,0 +1,315 @@
"""
Safe git-add helpers for Trellis-owned paths.
Why this module exists
----------------------
A real user incident: a project's `.gitignore` listed `.trellis/` (company-wide
template / personal habit). When `add_session.py` and `task.py archive` ran
their auto-commit and `git add` failed with `ignored by .gitignore`, the AI
agent driving the workflow "fixed" it by retrying with
`git add -f .trellis/` — which fan-out-included every ignored subtree
(`.trellis/.backup-*/`, `.trellis/worktrees/`, `.trellis/.template-hashes.json`,
`.trellis/.runtime/`), committing 548 files / 83474 lines of caches/backups.
Design
------
- Scripts only stage SPECIFIC product paths (journal files, index.md, the
current task dir, the archive dir). Never the whole `.trellis/` tree.
- If plain `git add <specific>` fails with "ignored by", DO NOT retry with
``-f``. The presence of `.trellis/` in `.gitignore` is treated as user
intent ("keep .trellis/ local-only"). The script warns and skips the
auto-commit; users who want auto-staging can either fix their `.gitignore`
or set ``session_auto_commit: false`` and manage git themselves.
- The warning includes a negative example: ``Do NOT use `git add -f .trellis/` ...``
so any AI rereading the log doesn't reinvent the bug.
History note: 0.5.10 introduced an automatic ``git add -f`` retry on the
specific paths. That was reverted in 0.5.11 — auto-forcing into a tree the
user had gitignored violates user intent even when the path list is narrow.
The wider-grain forbidden command stays forbidden, and the narrow-grain auto
``-f`` is gone too.
"""
from __future__ import annotations
import sys
from pathlib import Path
from .git import run_git
from .paths import (
DIR_ARCHIVE,
DIR_TASKS,
DIR_WORKFLOW,
DIR_WORKSPACE,
FILE_JOURNAL_PREFIX,
get_developer,
)
# Paths under .trellis/ that must NEVER be auto-staged. Listed here so the
# warning to the user can show concrete subpaths to ignore individually
# instead of ignoring the whole `.trellis/` tree.
TRELLIS_IGNORED_SUBPATHS = (
".trellis/.backup-*",
".trellis/worktrees/",
".trellis/.template-hashes.json",
".trellis/.runtime/",
".trellis/.cache/",
)
def safe_trellis_paths_to_add(
repo_root: Path,
task_name: str | None = None,
) -> list[str]:
"""Return the list of repo-relative paths the auto-commit should stage.
Only includes paths that exist on disk so callers don't pass non-existent
arguments to git. The caller is responsible for `git diff --cached`
checking afterwards.
Included:
- .trellis/workspace/<developer>/journal-*.md
- .trellis/workspace/<developer>/index.md
- .trellis/tasks/<task_name>/ (ONLY the current task dir when
``task_name`` is passed; plus its archive location if the task
already lives under archive/)
Excluded (intentionally — these must not be staged):
- .trellis/.backup-*, .trellis/worktrees/,
.trellis/.template-hashes.json, .trellis/.runtime/, .trellis/.cache/
Scope contract (see #303 / break-loop analysis): when ``task_name`` is
passed, the task segment stages ONLY that task directory — it never walks
``tasks_dir.iterdir()`` over all active tasks. This mirrors
:func:`safe_archive_paths_to_add` and prevents dirty changes in OTHER
parallel-window task dirs from being bundled into the session auto-commit.
Backwards-compat: with no ``task_name``, the function walks every active
task directory (+ the archive subtree) the old wide way. New callers
should always pass ``task_name``.
"""
paths: list[str] = []
# Workspace journal files + index.md
developer = get_developer(repo_root)
if developer:
ws = repo_root / DIR_WORKFLOW / DIR_WORKSPACE / developer
if ws.is_dir():
for f in sorted(ws.glob(f"{FILE_JOURNAL_PREFIX}*.md")):
if f.is_file():
paths.append(
f"{DIR_WORKFLOW}/{DIR_WORKSPACE}/{developer}/{f.name}"
)
index_md = ws / "index.md"
if index_md.is_file():
paths.append(
f"{DIR_WORKFLOW}/{DIR_WORKSPACE}/{developer}/index.md"
)
tasks_dir = repo_root / DIR_WORKFLOW / DIR_TASKS
if not tasks_dir.is_dir():
return paths
if task_name is not None:
# Narrow scope — ONLY the current task directory (active or archived).
# Never iterdir() all tasks: parallel-window dirty task dirs must not
# leak into the session auto-commit.
active_task = tasks_dir / task_name
if active_task.is_dir():
paths.append(f"{DIR_WORKFLOW}/{DIR_TASKS}/{task_name}")
archived_task = tasks_dir / DIR_ARCHIVE / task_name
if archived_task.is_dir():
paths.append(
f"{DIR_WORKFLOW}/{DIR_TASKS}/{DIR_ARCHIVE}/{task_name}"
)
return paths
# Legacy wide scope (no task_name): each direct child of tasks/ that is a
# directory and not the archive root, plus the whole archive subtree.
for child in sorted(tasks_dir.iterdir()):
if not child.is_dir():
continue
if child.name == DIR_ARCHIVE:
continue
paths.append(f"{DIR_WORKFLOW}/{DIR_TASKS}/{child.name}")
archive_dir = tasks_dir / DIR_ARCHIVE
if archive_dir.is_dir():
paths.append(f"{DIR_WORKFLOW}/{DIR_TASKS}/{DIR_ARCHIVE}")
return paths
def safe_archive_paths_to_add(
repo_root: Path,
task_name: str | None = None,
modified_children: list[str] | None = None,
) -> list[str]:
"""Return paths to stage after `task.py archive`.
Scoped to ONLY the paths the archive operation actually touched:
- the archive subtree (where the freshly-moved task lives)
- the source task directory (for source-side deletes; caller pairs
this with `git rm --cached` since `git add` won't stage deletes
for a path that no longer exists in the working tree)
- any child task directories whose `task.json` was edited to drop
the archived parent (parent-children relationship update)
This narrow scope avoids "scope creep" — dirty changes in OTHER
active task dirs (parallel-window edits) are NOT bundled into the
archive commit. Callers handle each kind of change in its own
commit boundary.
Backwards-compat: with no arguments, the function walks the whole
`.trellis/tasks/` subtree the old way (active tasks + archive). New
callers should always pass `task_name`.
"""
paths: list[str] = []
tasks_dir = repo_root / DIR_WORKFLOW / DIR_TASKS
if not tasks_dir.is_dir():
return paths
archive_dir = tasks_dir / DIR_ARCHIVE
if task_name is not None:
# Narrow scope — only paths that still exist on disk (so
# `git add` doesn't choke on the moved-away source). The caller
# handles the source-side deletes via `git rm --cached`
# explicitly.
if archive_dir.is_dir():
paths.append(
f"{DIR_WORKFLOW}/{DIR_TASKS}/{DIR_ARCHIVE}"
)
for child_name in modified_children or []:
paths.append(f"{DIR_WORKFLOW}/{DIR_TASKS}/{child_name}")
return paths
# Legacy wide scope (no task_name): preserve old behavior so callers
# that have not been updated keep working.
if archive_dir.is_dir():
paths.append(f"{DIR_WORKFLOW}/{DIR_TASKS}/{DIR_ARCHIVE}")
for child in sorted(tasks_dir.iterdir()):
if not child.is_dir():
continue
if child.name == DIR_ARCHIVE:
continue
paths.append(f"{DIR_WORKFLOW}/{DIR_TASKS}/{child.name}")
return paths
def _stderr_indicates_ignored(stderr: str) -> bool:
"""git add error indicates the path is excluded by .gitignore."""
if not stderr:
return False
lowered = stderr.lower()
return "ignored by" in lowered
def safe_git_add(
paths: list[str], repo_root: Path
) -> tuple[bool, bool, str]:
"""Run `git add` on specific paths; never retry with -f.
Returns ``(success, used_force, stderr)``. The ``used_force`` field is
kept for signature compatibility with the 0.5.10 implementation but is
always ``False`` — we never auto-force.
Behavior:
- No paths passed → success, no force, empty stderr.
- Plain ``git add -- <paths>`` succeeds → return success.
- Plain fails (any reason — ignored or otherwise) → return failure with
the stderr. Callers should inspect the stderr (see
:func:`print_gitignore_warning`) and skip the auto-commit.
"""
if not paths:
return True, False, ""
rc, _, err = run_git(["add", "--", *paths], cwd=repo_root)
if rc == 0:
return True, False, ""
return False, False, err
def print_gitignore_warning(paths: list[str]) -> None:
"""Explain to the user (and any AI reading the log) what to do.
CRITICAL: includes the negative example
``Do NOT use `git add -f .trellis/``` — agents reading the warning are
known to invent that command, which fans out to ignored caches/backups.
"""
print(
"[WARN] git add failed because .trellis/ paths are ignored by your .gitignore.",
file=sys.stderr,
)
print(
"[WARN] Skipping auto-commit. The journal/task files were still written to disk;",
file=sys.stderr,
)
print(
"[WARN] git was not touched.",
file=sys.stderr,
)
print("[WARN]", file=sys.stderr)
print(
"[WARN] Trellis manages these specific paths and they should be tracked:",
file=sys.stderr,
)
if paths:
for p in paths:
print(f"[WARN] {p}", file=sys.stderr)
else:
print(
"[WARN] .trellis/workspace/<developer>/{journal-*.md,index.md}",
file=sys.stderr,
)
print(
"[WARN] .trellis/tasks/<task-dir>/",
file=sys.stderr,
)
print(
"[WARN] .trellis/tasks/archive/",
file=sys.stderr,
)
print("[WARN]", file=sys.stderr)
print(
"[WARN] Recommended: change your .gitignore from `.trellis/` to specific",
file=sys.stderr,
)
print(
"[WARN] subpaths that should remain ignored, e.g.:",
file=sys.stderr,
)
for sub in TRELLIS_IGNORED_SUBPATHS:
print(f"[WARN] {sub}", file=sys.stderr)
print("[WARN]", file=sys.stderr)
print(
"[WARN] Or, if you intentionally keep .trellis/ local-only, set in",
file=sys.stderr,
)
print(
"[WARN] .trellis/config.yaml:",
file=sys.stderr,
)
print(
"[WARN] session_auto_commit: false",
file=sys.stderr,
)
print(
"[WARN] so the scripts skip git entirely and you can review / commit",
file=sys.stderr,
)
print(
"[WARN] manually with `git status` / `git add` / `git commit`.",
file=sys.stderr,
)
print("[WARN]", file=sys.stderr)
print(
"[WARN] Do NOT use `git add -f .trellis/` — it pulls in backups, worktrees,",
file=sys.stderr,
)
print(
"[WARN] and runtime caches that should never be committed.",
file=sys.stderr,
)
.trellis/scripts/common/session_context.py
Executable
+821
View File
@@ -0,0 +1,821 @@
#!/usr/bin/env python3
"""
Session context generation (default + record modes).
Provides:
get_context_json - JSON output for default mode
get_context_text - Text output for default mode
get_context_record_json - JSON for record mode
get_context_text_record - Text for record mode
output_json - Print JSON
output_text - Print text
"""
from __future__ import annotations
import json
import os
import re
import subprocess
from pathlib import Path
from .active_task import resolve_context_key
from .config import get_git_packages
from .git import run_git
from .packages_context import get_packages_section
from .tasks import iter_active_tasks, load_task, get_all_statuses, children_progress
from .paths import (
DIR_SCRIPTS,
DIR_SPEC,
DIR_TASKS,
DIR_WORKFLOW,
DIR_WORKSPACE,
count_lines,
get_active_journal_file,
get_current_task,
get_current_task_source,
get_developer,
get_repo_root,
get_tasks_dir,
)
# =============================================================================
# Helpers
# =============================================================================
_PACKAGE_NAME = "@mindfoldhq/trellis"
_UPDATE_CHECK_TIMEOUT_SECONDS = 1.0
_VERSION_RE = re.compile(
r"^\s*(\d+)(?:\.(\d+))?(?:\.(\d+))?(?:-([0-9A-Za-z.-]+))?\s*$"
)
_VERSION_TOKEN_RE = re.compile(r"\b\d+(?:\.\d+){1,2}(?:-[0-9A-Za-z.-]+)?\b")
_POLYREPO_IGNORED_DIRS = {
"node_modules",
"target",
"dist",
"build",
"out",
"bin",
"obj",
"vendor",
"coverage",
"tmp",
"__pycache__",
}
_POLYREPO_SCAN_MAX_DEPTH = 2
def _is_git_worktree(path: Path) -> bool:
"""Return True when path is inside a Git worktree."""
rc, out, _ = run_git(["rev-parse", "--is-inside-work-tree"], cwd=path)
return rc == 0 and out.strip().lower() == "true"
def _parse_recent_commits(log_output: str) -> list[dict]:
"""Parse `git log --oneline` output into structured commit entries."""
commits = []
for line in log_output.splitlines():
if not line.strip():
continue
parts = line.split(" ", 1)
if len(parts) >= 2:
commits.append({"hash": parts[0], "message": parts[1]})
elif len(parts) == 1:
commits.append({"hash": parts[0], "message": ""})
return commits
def _collect_git_repo_info(name: str, rel_path: str, repo_dir: Path) -> dict | None:
"""Collect Git status for one known repository directory."""
if not (repo_dir / ".git").exists():
return None
_, branch_out, _ = run_git(["branch", "--show-current"], cwd=repo_dir)
branch = branch_out.strip() or "unknown"
_, status_out, _ = run_git(["status", "--porcelain"], cwd=repo_dir)
changes = len([l for l in status_out.splitlines() if l.strip()])
_, log_out, _ = run_git(["log", "--oneline", "-5"], cwd=repo_dir)
return {
"name": name,
"path": rel_path,
"branch": branch,
"isClean": changes == 0,
"uncommittedChanges": changes,
"recentCommits": _parse_recent_commits(log_out),
}
def _collect_root_git_info(repo_root: Path) -> dict:
"""Collect root Git info without pretending a non-Git root is clean."""
if not _is_git_worktree(repo_root):
return {
"isRepo": False,
"branch": "",
"isClean": False,
"uncommittedChanges": 0,
"recentCommits": [],
}
_, branch_out, _ = run_git(["branch", "--show-current"], cwd=repo_root)
branch = branch_out.strip() or "unknown"
_, status_out, _ = run_git(["status", "--porcelain"], cwd=repo_root)
status_lines = [line for line in status_out.splitlines() if line.strip()]
_, short_out, _ = run_git(["status", "--short"], cwd=repo_root)
_, log_out, _ = run_git(["log", "--oneline", "-5"], cwd=repo_root)
return {
"isRepo": True,
"branch": branch,
"isClean": len(status_lines) == 0,
"uncommittedChanges": len(status_lines),
"statusShort": short_out.splitlines(),
"recentCommits": _parse_recent_commits(log_out),
}
def _discover_child_git_repos(repo_root: Path) -> list[tuple[str, str]]:
"""Discover child Git repositories using the init-time polyrepo heuristic."""
found: list[str] = []
def is_candidate_dir(path: Path) -> bool:
name = path.name
return not name.startswith(".") and name not in _POLYREPO_IGNORED_DIRS
def scan(rel_dir: Path, depth: int) -> None:
if depth >= _POLYREPO_SCAN_MAX_DEPTH:
return
abs_dir = repo_root / rel_dir
try:
children = sorted(abs_dir.iterdir(), key=lambda p: p.name)
except OSError:
return
for child in children:
if not child.is_dir() or not is_candidate_dir(child):
continue
child_rel = (
rel_dir / child.name if rel_dir != Path(".") else Path(child.name)
)
if (child / ".git").exists():
found.append(child_rel.as_posix())
continue
scan(child_rel, depth + 1)
scan(Path("."), 0)
if len(found) < 2:
return []
return [(path.replace("/", "_"), path) for path in sorted(found)]
def _collect_package_git_info(
repo_root: Path,
discover_unconfigured: bool = False,
) -> list[dict]:
"""Collect Git status for independent package repositories.
Packages marked with ``git: true`` in config.yaml are authoritative.
When the Trellis root is not a Git repo and no configured package repos are
available, optionally fall back to the bounded polyrepo child scan.
Returns:
List of dicts with keys: name, path, branch, isClean,
uncommittedChanges, recentCommits.
Empty list if no git-repo packages are configured.
"""
git_pkgs = get_git_packages(repo_root)
result = []
for pkg_name, pkg_path in git_pkgs.items():
pkg_dir = repo_root / pkg_path
info = _collect_git_repo_info(pkg_name, pkg_path, pkg_dir)
if info is not None:
result.append(info)
if result or not discover_unconfigured:
return result
discovered = []
for pkg_name, pkg_path in _discover_child_git_repos(repo_root):
info = _collect_git_repo_info(pkg_name, pkg_path, repo_root / pkg_path)
if info is not None:
discovered.append(info)
return discovered
def _append_root_git_context(lines: list[str], root_git_info: dict) -> None:
"""Append root Git status without misleading non-Git roots."""
lines.append("## GIT STATUS")
if not root_git_info["isRepo"]:
lines.append("Root is not a Git repository.")
lines.append("Run Git commands from the package repository paths listed below.")
else:
lines.append(f"Branch: {root_git_info['branch']}")
if root_git_info["isClean"]:
lines.append("Working directory: Clean")
else:
lines.append(
f"Working directory: {root_git_info['uncommittedChanges']} "
"uncommitted change(s)"
)
lines.append("")
lines.append("Changes:")
for line in root_git_info.get("statusShort", [])[:10]:
lines.append(line)
lines.append("")
lines.append("## RECENT COMMITS")
if not root_git_info["isRepo"]:
lines.append(
"Root has no Git commit history because it is not a Git repository."
)
elif root_git_info["recentCommits"]:
for commit in root_git_info["recentCommits"]:
lines.append(f"{commit['hash']} {commit['message']}")
else:
lines.append("(no commits)")
lines.append("")
def _append_package_git_context(lines: list[str], package_git_info: list[dict]) -> None:
"""Append Git status and recent commits for package repositories."""
for pkg in package_git_info:
lines.append(f"## GIT STATUS ({pkg['name']}: {pkg['path']})")
lines.append(f"Branch: {pkg['branch']}")
if pkg["isClean"]:
lines.append("Working directory: Clean")
else:
lines.append(
f"Working directory: {pkg['uncommittedChanges']} uncommitted change(s)"
)
lines.append("")
lines.append(f"## RECENT COMMITS ({pkg['name']}: {pkg['path']})")
if pkg["recentCommits"]:
for commit in pkg["recentCommits"]:
lines.append(f"{commit['hash']} {commit['message']}")
else:
lines.append("(no commits)")
lines.append("")
def _read_project_version(repo_root: Path) -> str | None:
try:
version = (repo_root / DIR_WORKFLOW / ".version").read_text(
encoding="utf-8"
).strip()
except OSError:
return None
return version or None
def _fetch_trellis_version_output() -> str | None:
try:
result = subprocess.run(
["trellis", "--version"],
capture_output=True,
text=True,
encoding="utf-8",
errors="replace",
timeout=_UPDATE_CHECK_TIMEOUT_SECONDS,
)
except (OSError, subprocess.SubprocessError, TimeoutError):
return None
if result.returncode != 0:
return None
output = f"{result.stdout}\n{result.stderr}".strip()
return output or None
def _extract_available_update_version(output: str) -> str | None:
update_match = re.search(
r"Trellis update available:\s*"
r"(?P<current>\S+)\s*(?:→|->)\s*(?P<latest>\S+)",
output,
)
if update_match:
return update_match.group("latest").strip()
candidates = _VERSION_TOKEN_RE.findall(output)
return candidates[-1] if candidates else None
def _resolve_available_update_version() -> str | None:
output = _fetch_trellis_version_output()
if not output:
return None
return _extract_available_update_version(output)
def _parse_version(version: str) -> tuple[tuple[int, int, int], tuple[str, ...] | None] | None:
match = _VERSION_RE.match(version)
if not match:
return None
major, minor, patch, prerelease = match.groups()
numbers = (int(major), int(minor or "0"), int(patch or "0"))
prerelease_parts = tuple(prerelease.split(".")) if prerelease else None
return numbers, prerelease_parts
def _compare_prerelease(
left: tuple[str, ...] | None,
right: tuple[str, ...] | None,
) -> int:
if left is None and right is None:
return 0
if left is None:
return 1
if right is None:
return -1
for left_part, right_part in zip(left, right):
if left_part == right_part:
continue
left_numeric = left_part.isdigit()
right_numeric = right_part.isdigit()
if left_numeric and right_numeric:
left_int = int(left_part)
right_int = int(right_part)
return (left_int > right_int) - (left_int < right_int)
if left_numeric:
return -1
if right_numeric:
return 1
return (left_part > right_part) - (left_part < right_part)
return (len(left) > len(right)) - (len(left) < len(right))
def _compare_versions(left: str, right: str) -> int | None:
parsed_left = _parse_version(left)
parsed_right = _parse_version(right)
if parsed_left is None or parsed_right is None:
return None
left_numbers, left_prerelease = parsed_left
right_numbers, right_prerelease = parsed_right
if left_numbers != right_numbers:
return (left_numbers > right_numbers) - (left_numbers < right_numbers)
return _compare_prerelease(left_prerelease, right_prerelease)
def _update_marker_path(repo_root: Path) -> Path:
context_key = resolve_context_key()
if not context_key:
terminal_key = os.environ.get("TERM_SESSION_ID", "").strip()
context_key = terminal_key or f"ppid-{os.getppid()}"
safe_key = re.sub(r"[^A-Za-z0-9._-]+", "_", context_key).strip("._-")
if not safe_key:
safe_key = "session"
return (
repo_root
/ DIR_WORKFLOW
/ ".runtime"
/ f"update-check-{safe_key[:160]}.marker"
)
def _mark_update_check_attempted(repo_root: Path) -> bool:
marker_path = _update_marker_path(repo_root)
if marker_path.exists():
return False
try:
marker_path.parent.mkdir(parents=True, exist_ok=True)
marker_path.write_text("checked\n", encoding="utf-8")
except OSError:
pass
return True
def _get_update_hint(repo_root: Path) -> str | None:
marker_path = _update_marker_path(repo_root)
if marker_path.exists():
return None
current_version = _read_project_version(repo_root)
if not current_version:
return None
latest_version = _resolve_available_update_version()
if not latest_version:
return None
_mark_update_check_attempted(repo_root)
comparison = _compare_versions(current_version, latest_version)
if comparison is None or comparison >= 0:
return None
return (
f"Trellis update available: {current_version} -> {latest_version}, "
"run trellis upgrade"
)
# =============================================================================
# JSON Output
# =============================================================================
def get_context_json(repo_root: Path | None = None) -> dict:
"""Get context as a dictionary.
Args:
repo_root: Repository root path. Defaults to auto-detected.
Returns:
Context dictionary.
"""
if repo_root is None:
repo_root = get_repo_root()
developer = get_developer(repo_root)
tasks_dir = get_tasks_dir(repo_root)
journal_file = get_active_journal_file(repo_root)
journal_lines = 0
journal_relative = ""
if journal_file and developer:
journal_lines = count_lines(journal_file)
journal_relative = (
f"{DIR_WORKFLOW}/{DIR_WORKSPACE}/{developer}/{journal_file.name}"
)
root_git_info = _collect_root_git_info(repo_root)
# Tasks
tasks = [
{
"dir": t.dir_name,
"name": t.name,
"status": t.status,
"children": list(t.children),
"parent": t.parent,
}
for t in iter_active_tasks(tasks_dir)
]
# Package git repos (independent sub-repositories)
pkg_git_info = _collect_package_git_info(
repo_root,
discover_unconfigured=not root_git_info["isRepo"],
)
result = {
"developer": developer or "",
"git": {
"isRepo": root_git_info["isRepo"],
"branch": root_git_info["branch"],
"isClean": root_git_info["isClean"],
"uncommittedChanges": root_git_info["uncommittedChanges"],
"recentCommits": root_git_info["recentCommits"],
},
"tasks": {
"active": tasks,
"directory": f"{DIR_WORKFLOW}/{DIR_TASKS}",
},
"journal": {
"file": journal_relative,
"lines": journal_lines,
"nearLimit": journal_lines > 1800,
},
}
if pkg_git_info:
result["packageGit"] = pkg_git_info
return result
def output_json(repo_root: Path | None = None) -> None:
"""Output context in JSON format.
Args:
repo_root: Repository root path. Defaults to auto-detected.
"""
context = get_context_json(repo_root)
print(json.dumps(context, indent=2, ensure_ascii=False))
# =============================================================================
# Text Output
# =============================================================================
def get_context_text(repo_root: Path | None = None) -> str:
"""Get context as formatted text.
Args:
repo_root: Repository root path. Defaults to auto-detected.
Returns:
Formatted text output.
"""
if repo_root is None:
repo_root = get_repo_root()
lines = []
lines.append("========================================")
lines.append("SESSION CONTEXT")
lines.append("========================================")
lines.append("")
developer = get_developer(repo_root)
# Developer section
lines.append("## DEVELOPER")
if not developer:
lines.append(
f"ERROR: Not initialized. Run: python3 ./{DIR_WORKFLOW}/{DIR_SCRIPTS}/init_developer.py <name>"
)
return "\n".join(lines)
lines.append(f"Name: {developer}")
lines.append("")
root_git_info = _collect_root_git_info(repo_root)
_append_root_git_context(lines, root_git_info)
# Package git repos — independent sub-repositories
_append_package_git_context(
lines,
_collect_package_git_info(
repo_root,
discover_unconfigured=not root_git_info["isRepo"],
),
)
# Current task
lines.append("## CURRENT TASK")
current_task = get_current_task(repo_root)
if current_task:
current_task_dir = repo_root / current_task
source_type, context_key, _ = get_current_task_source(repo_root)
lines.append(f"Path: {current_task}")
lines.append(
f"Source: {source_type}" + (f":{context_key}" if context_key else "")
)
ct = load_task(current_task_dir)
if ct:
lines.append(f"Name: {ct.name}")
lines.append(f"Status: {ct.status}")
lines.append(f"Created: {ct.raw.get('createdAt', 'unknown')}")
if ct.description:
lines.append(f"Description: {ct.description}")
# Check for prd.md
prd_file = current_task_dir / "prd.md"
if prd_file.is_file():
lines.append("")
lines.append("[!] This task has prd.md - read it for task details")
else:
lines.append("(none)")
lines.append("")
# Active tasks
lines.append("## ACTIVE TASKS")
tasks_dir = get_tasks_dir(repo_root)
task_count = 0
# Collect all task data for hierarchy display
all_tasks = {t.dir_name: t for t in iter_active_tasks(tasks_dir)}
all_statuses = {name: t.status for name, t in all_tasks.items()}
def _print_task_tree(name: str, indent: int = 0) -> None:
nonlocal task_count
t = all_tasks[name]
progress = children_progress(t.children, all_statuses)
prefix = " " * indent
lines.append(f"{prefix}- {name}/ ({t.status}){progress} @{t.assignee or '-'}")
task_count += 1
for child in t.children:
if child in all_tasks:
_print_task_tree(child, indent + 1)
for dir_name in sorted(all_tasks.keys()):
if not all_tasks[dir_name].parent:
_print_task_tree(dir_name)
if task_count == 0:
lines.append("(no active tasks)")
lines.append(f"Total: {task_count} active task(s)")
lines.append("")
# My tasks
lines.append("## MY TASKS (Assigned to me)")
my_task_count = 0
for t in all_tasks.values():
if t.assignee == developer and t.status != "done":
progress = children_progress(t.children, all_statuses)
lines.append(f"- [{t.priority}] {t.title} ({t.status}){progress}")
my_task_count += 1
if my_task_count == 0:
lines.append("(no tasks assigned to you)")
lines.append("")
# Journal file
lines.append("## JOURNAL FILE")
journal_file = get_active_journal_file(repo_root)
if journal_file:
journal_lines = count_lines(journal_file)
relative = f"{DIR_WORKFLOW}/{DIR_WORKSPACE}/{developer}/{journal_file.name}"
lines.append(f"Active file: {relative}")
lines.append(f"Line count: {journal_lines} / 2000")
if journal_lines > 1800:
lines.append("[!] WARNING: Approaching 2000 line limit!")
else:
lines.append("No journal file found")
lines.append("")
# Packages
packages_text = get_packages_section(repo_root)
if packages_text:
lines.append(packages_text)
lines.append("")
# Paths
lines.append("## PATHS")
lines.append(f"Workspace: {DIR_WORKFLOW}/{DIR_WORKSPACE}/{developer}/")
lines.append(f"Tasks: {DIR_WORKFLOW}/{DIR_TASKS}/")
lines.append(f"Spec: {DIR_WORKFLOW}/{DIR_SPEC}/")
lines.append("")
lines.append("========================================")
return "\n".join(lines)
# =============================================================================
# Record Mode
# =============================================================================
def get_context_record_json(repo_root: Path | None = None) -> dict:
"""Get record-mode context as a dictionary.
Focused on: my active tasks, git status, current task.
"""
if repo_root is None:
repo_root = get_repo_root()
developer = get_developer(repo_root)
tasks_dir = get_tasks_dir(repo_root)
root_git_info = _collect_root_git_info(repo_root)
# My tasks (single pass — collect statuses and filter by assignee)
all_tasks_list = list(iter_active_tasks(tasks_dir))
all_statuses = {t.dir_name: t.status for t in all_tasks_list}
my_tasks = []
for t in all_tasks_list:
if t.assignee == developer:
done = sum(
1 for c in t.children
if all_statuses.get(c) in ("completed", "done")
)
my_tasks.append({
"dir": t.dir_name,
"title": t.title,
"status": t.status,
"priority": t.priority,
"children": list(t.children),
"childrenDone": done,
"parent": t.parent,
"meta": t.meta,
})
# Current task
current_task_info = None
current_task = get_current_task(repo_root)
if current_task:
source_type, context_key, _ = get_current_task_source(repo_root)
ct = load_task(repo_root / current_task)
if ct:
current_task_info = {
"path": current_task,
"name": ct.name,
"status": ct.status,
"source": source_type,
"contextKey": context_key,
}
# Package git repos
pkg_git_info = _collect_package_git_info(
repo_root,
discover_unconfigured=not root_git_info["isRepo"],
)
result = {
"developer": developer or "",
"git": {
"isRepo": root_git_info["isRepo"],
"branch": root_git_info["branch"],
"isClean": root_git_info["isClean"],
"uncommittedChanges": root_git_info["uncommittedChanges"],
"recentCommits": root_git_info["recentCommits"],
},
"myTasks": my_tasks,
"currentTask": current_task_info,
}
if pkg_git_info:
result["packageGit"] = pkg_git_info
return result
def get_context_text_record(repo_root: Path | None = None) -> str:
"""Get context as formatted text for record-session mode.
Focused output: MY ACTIVE TASKS first (with [!!!] emphasis),
then GIT STATUS, RECENT COMMITS, CURRENT TASK.
"""
if repo_root is None:
repo_root = get_repo_root()
lines: list[str] = []
lines.append("========================================")
lines.append("SESSION CONTEXT (RECORD MODE)")
lines.append("========================================")
lines.append("")
developer = get_developer(repo_root)
if not developer:
lines.append(
f"ERROR: Not initialized. Run: python3 ./{DIR_WORKFLOW}/{DIR_SCRIPTS}/init_developer.py <name>"
)
return "\n".join(lines)
# MY ACTIVE TASKS — first and prominent
lines.append(f"## [!!!] MY ACTIVE TASKS (Assigned to {developer})")
lines.append("[!] Review whether any should be archived before recording this session.")
lines.append("")
tasks_dir = get_tasks_dir(repo_root)
my_task_count = 0
# Single pass — collect all tasks and filter by assignee
all_statuses = get_all_statuses(tasks_dir)
for t in iter_active_tasks(tasks_dir):
if t.assignee == developer:
progress = children_progress(t.children, all_statuses)
lines.append(f"- [{t.priority}] {t.title} ({t.status}){progress} — {t.dir_name}")
my_task_count += 1
if my_task_count == 0:
lines.append("(no active tasks assigned to you)")
lines.append("")
root_git_info = _collect_root_git_info(repo_root)
_append_root_git_context(lines, root_git_info)
# Package git repos — independent sub-repositories
_append_package_git_context(
lines,
_collect_package_git_info(
repo_root,
discover_unconfigured=not root_git_info["isRepo"],
),
)
# CURRENT TASK
lines.append("## CURRENT TASK")
current_task = get_current_task(repo_root)
if current_task:
source_type, context_key, _ = get_current_task_source(repo_root)
lines.append(f"Path: {current_task}")
lines.append(
f"Source: {source_type}" + (f":{context_key}" if context_key else "")
)
ct = load_task(repo_root / current_task)
if ct:
lines.append(f"Name: {ct.name}")
lines.append(f"Status: {ct.status}")
else:
lines.append("(none)")
lines.append("")
lines.append("========================================")
return "\n".join(lines)
def output_text(repo_root: Path | None = None) -> None:
"""Output context in text format.
Args:
repo_root: Repository root path. Defaults to auto-detected.
"""
if repo_root is None:
repo_root = get_repo_root()
update_hint = _get_update_hint(repo_root)
if update_hint:
print(update_hint)
print("")
print(get_context_text(repo_root))
.trellis/scripts/common/task_context.py
Executable
+223
View File
@@ -0,0 +1,223 @@
#!/usr/bin/env python3
"""
Task JSONL context management.
Provides:
cmd_add_context - Add entry to JSONL context file
cmd_validate - Validate JSONL context files
cmd_list_context - List JSONL context entries
Note:
``cmd_init_context`` was removed in v0.5.0-beta.12. JSONL context files
are now seeded at ``task.py create`` time with a self-describing
``_example`` line; the AI agent curates real entries during planning when
the task needs sub-agent/spec context. See ``.trellis/workflow.md`` for the
current planning artifact contract.
"""
from __future__ import annotations
import argparse
import json
from pathlib import Path
from .log import Colors, colored
from .paths import get_repo_root
from .task_utils import resolve_task_dir
# =============================================================================
# Command: add-context
# =============================================================================
def cmd_add_context(args: argparse.Namespace) -> int:
"""Add entry to JSONL context file."""
repo_root = get_repo_root()
target_dir = resolve_task_dir(args.dir, repo_root)
jsonl_name = args.file
path = args.path
reason = args.reason or "Added manually"
if not target_dir.is_dir():
print(colored(f"Error: Directory not found: {target_dir}", Colors.RED))
return 1
# Support shorthand
if not jsonl_name.endswith(".jsonl"):
jsonl_name = f"{jsonl_name}.jsonl"
jsonl_file = target_dir / jsonl_name
full_path = repo_root / path
entry_type = "file"
if full_path.is_dir():
entry_type = "directory"
if not path.endswith("/"):
path = f"{path}/"
elif not full_path.is_file():
print(colored(f"Error: Path not found: {path}", Colors.RED))
return 1
# Check if already exists
if jsonl_file.is_file():
content = jsonl_file.read_text(encoding="utf-8")
if f'"{path}"' in content:
print(colored(f"Warning: Entry already exists for {path}", Colors.YELLOW))
return 0
# Add entry
entry: dict
if entry_type == "directory":
entry = {"file": path, "type": "directory", "reason": reason}
else:
entry = {"file": path, "reason": reason}
with jsonl_file.open("a", encoding="utf-8") as f:
f.write(json.dumps(entry, ensure_ascii=False) + "\n")
print(colored(f"Added {entry_type}: {path}", Colors.GREEN))
return 0
# =============================================================================
# Command: validate
# =============================================================================
def cmd_validate(args: argparse.Namespace) -> int:
"""Validate JSONL context files."""
repo_root = get_repo_root()
target_dir = resolve_task_dir(args.dir, repo_root)
if not target_dir.is_dir():
print(colored("Error: task directory required", Colors.RED))
return 1
print(colored("=== Validating Context Files ===", Colors.BLUE))
print(f"Target dir: {target_dir}")
print()
total_errors = 0
for jsonl_name in ["implement.jsonl", "check.jsonl"]:
jsonl_file = target_dir / jsonl_name
errors = _validate_jsonl(jsonl_file, repo_root)
total_errors += errors
print()
if total_errors == 0:
print(colored("✓ All validations passed", Colors.GREEN))
return 0
else:
print(colored(f"✗ Validation failed ({total_errors} errors)", Colors.RED))
return 1
def _validate_jsonl(jsonl_file: Path, repo_root: Path) -> int:
"""Validate a single JSONL file.
Seed rows (no ``file`` field — typically ``{"_example": "..."}``) are
skipped silently; they are self-describing comments, not real entries.
"""
file_name = jsonl_file.name
errors = 0
if not jsonl_file.is_file():
print(f" {colored(f'{file_name}: not found (skipped)', Colors.YELLOW)}")
return 0
line_num = 0
real_entries = 0
for line in jsonl_file.read_text(encoding="utf-8").splitlines():
line_num += 1
if not line.strip():
continue
try:
data = json.loads(line)
except json.JSONDecodeError:
print(f" {colored(f'{file_name}:{line_num}: Invalid JSON', Colors.RED)}")
errors += 1
continue
file_path = data.get("file")
entry_type = data.get("type", "file")
if not file_path:
# Seed / comment row — skip silently
continue
real_entries += 1
full_path = repo_root / file_path
if entry_type == "directory":
if not full_path.is_dir():
print(f" {colored(f'{file_name}:{line_num}: Directory not found: {file_path}', Colors.RED)}")
errors += 1
else:
if not full_path.is_file():
print(f" {colored(f'{file_name}:{line_num}: File not found: {file_path}', Colors.RED)}")
errors += 1
if errors == 0:
print(f" {colored(f'{file_name}: ✓ ({real_entries} entries)', Colors.GREEN)}")
else:
print(f" {colored(f'{file_name}: ✗ ({errors} errors)', Colors.RED)}")
return errors
# =============================================================================
# Command: list-context
# =============================================================================
def cmd_list_context(args: argparse.Namespace) -> int:
"""List JSONL context entries."""
repo_root = get_repo_root()
target_dir = resolve_task_dir(args.dir, repo_root)
if not target_dir.is_dir():
print(colored("Error: task directory required", Colors.RED))
return 1
print(colored("=== Context Files ===", Colors.BLUE))
print()
for jsonl_name in ["implement.jsonl", "check.jsonl"]:
jsonl_file = target_dir / jsonl_name
if not jsonl_file.is_file():
continue
print(colored(f"[{jsonl_name}]", Colors.CYAN))
count = 0
seed_only = True
for line in jsonl_file.read_text(encoding="utf-8").splitlines():
if not line.strip():
continue
try:
data = json.loads(line)
except json.JSONDecodeError:
continue
file_path = data.get("file")
if not file_path:
# Seed / comment row — don't count as a real entry
continue
seed_only = False
count += 1
entry_type = data.get("type", "file")
reason = data.get("reason", "-")
if entry_type == "directory":
print(f" {colored(f'{count}.', Colors.GREEN)} [DIR] {file_path}")
else:
print(f" {colored(f'{count}.', Colors.GREEN)} {file_path}")
print(f" {colored('→', Colors.YELLOW)} {reason}")
if seed_only:
print(f" {colored('(no curated entries yet — only seed row)', Colors.YELLOW)}")
print()
return 0
.trellis/scripts/common/task_queue.py
Executable
+188
View File
@@ -0,0 +1,188 @@
#!/usr/bin/env python3
"""
Task queue utility functions.
Provides:
list_tasks_by_status - List tasks by status
list_pending_tasks - List tasks with pending status
list_tasks_by_assignee - List tasks by assignee
list_my_tasks - List tasks assigned to current developer
get_task_stats - Get P0/P1/P2/P3 counts
"""
from __future__ import annotations
from pathlib import Path
from .paths import (
get_repo_root,
get_developer,
get_tasks_dir,
)
from .tasks import iter_active_tasks
# =============================================================================
# Internal helper
# =============================================================================
def _task_to_dict(t) -> dict:
"""Convert TaskInfo to the dict format callers expect."""
return {
"priority": t.priority,
"id": t.raw.get("id", ""),
"title": t.title,
"status": t.status,
"assignee": t.assignee or "-",
"dir": t.dir_name,
"children": list(t.children),
"parent": t.parent,
}
# =============================================================================
# Public Functions
# =============================================================================
def list_tasks_by_status(
filter_status: str | None = None,
repo_root: Path | None = None
) -> list[dict]:
"""List tasks by status.
Args:
filter_status: Optional status filter.
repo_root: Repository root path. Defaults to auto-detected.
Returns:
List of task info dicts with keys: priority, id, title, status, assignee.
"""
if repo_root is None:
repo_root = get_repo_root()
tasks_dir = get_tasks_dir(repo_root)
results = []
for t in iter_active_tasks(tasks_dir):
if filter_status and t.status != filter_status:
continue
results.append(_task_to_dict(t))
return results
def list_pending_tasks(repo_root: Path | None = None) -> list[dict]:
"""List pending tasks.
Args:
repo_root: Repository root path. Defaults to auto-detected.
Returns:
List of task info dicts.
"""
return list_tasks_by_status("planning", repo_root)
def list_tasks_by_assignee(
assignee: str,
filter_status: str | None = None,
repo_root: Path | None = None
) -> list[dict]:
"""List tasks assigned to a specific developer.
Args:
assignee: Developer name.
filter_status: Optional status filter.
repo_root: Repository root path. Defaults to auto-detected.
Returns:
List of task info dicts.
"""
if repo_root is None:
repo_root = get_repo_root()
tasks_dir = get_tasks_dir(repo_root)
results = []
for t in iter_active_tasks(tasks_dir):
if (t.assignee or "-") != assignee:
continue
if filter_status and t.status != filter_status:
continue
results.append(_task_to_dict(t))
return results
def list_my_tasks(
filter_status: str | None = None,
repo_root: Path | None = None
) -> list[dict]:
"""List tasks assigned to current developer.
Args:
filter_status: Optional status filter.
repo_root: Repository root path. Defaults to auto-detected.
Returns:
List of task info dicts.
Raises:
ValueError: If developer not set.
"""
if repo_root is None:
repo_root = get_repo_root()
developer = get_developer(repo_root)
if not developer:
raise ValueError("Developer not set")
return list_tasks_by_assignee(developer, filter_status, repo_root)
def get_task_stats(repo_root: Path | None = None) -> dict[str, int]:
"""Get task statistics.
Args:
repo_root: Repository root path. Defaults to auto-detected.
Returns:
Dict with keys: P0, P1, P2, P3, Total.
"""
if repo_root is None:
repo_root = get_repo_root()
tasks_dir = get_tasks_dir(repo_root)
stats = {"P0": 0, "P1": 0, "P2": 0, "P3": 0, "Total": 0}
for t in iter_active_tasks(tasks_dir):
if t.priority in stats:
stats[t.priority] += 1
stats["Total"] += 1
return stats
def format_task_stats(stats: dict[str, int]) -> str:
"""Format task stats as string.
Args:
stats: Stats dict from get_task_stats.
Returns:
Formatted string like "P0:0 P1:1 P2:2 P3:0 Total:3".
"""
return f"P0:{stats['P0']} P1:{stats['P1']} P2:{stats['P2']} P3:{stats['P3']} Total:{stats['Total']}"
# =============================================================================
# Main Entry (for testing)
# =============================================================================
if __name__ == "__main__":
stats = get_task_stats()
print(format_task_stats(stats))
print()
print("Pending tasks:")
for task in list_pending_tasks():
print(f" {task['priority']}|{task['id']}|{task['title']}|{task['status']}|{task['assignee']}")
.trellis/scripts/common/task_store.py
Executable
+746
View File
@@ -0,0 +1,746 @@
#!/usr/bin/env python3
"""
Task CRUD operations.
Provides:
ensure_tasks_dir - Ensure tasks directory exists
cmd_create - Create a new task
cmd_archive - Archive completed task
cmd_set_branch - Set git branch for task
cmd_set_base_branch - Set PR target branch
cmd_set_scope - Set scope for PR title
cmd_add_subtask - Link child task to parent
cmd_remove_subtask - Unlink child task from parent
"""
from __future__ import annotations
import argparse
import json
import re
import sys
from datetime import datetime
from pathlib import Path
from .config import (
get_packages,
get_session_auto_commit,
is_monorepo,
resolve_package,
validate_package,
)
from .git import run_git
from .io import read_json, write_json
from .log import Colors, colored
from .paths import (
DIR_ARCHIVE,
DIR_TASKS,
DIR_WORKFLOW,
FILE_TASK_JSON,
generate_task_date_prefix,
get_developer,
get_repo_root,
get_tasks_dir,
)
from .safe_commit import (
print_gitignore_warning,
safe_archive_paths_to_add,
safe_git_add,
)
from .task_utils import (
archive_task_complete,
find_task_by_name,
resolve_task_dir,
run_task_hooks,
)
# =============================================================================
# Helper Functions
# =============================================================================
def _slugify(title: str) -> str:
"""Convert title to slug (only works with ASCII)."""
result = title.lower()
result = re.sub(r"[^a-z0-9]", "-", result)
result = re.sub(r"-+", "-", result)
result = result.strip("-")
return result
def ensure_tasks_dir(repo_root: Path) -> Path:
"""Ensure tasks directory exists."""
tasks_dir = get_tasks_dir(repo_root)
archive_dir = tasks_dir / "archive"
if not tasks_dir.exists():
tasks_dir.mkdir(parents=True)
print(colored(f"Created tasks directory: {tasks_dir}", Colors.GREEN), file=sys.stderr)
if not archive_dir.exists():
archive_dir.mkdir(parents=True)
return tasks_dir
def _find_archived_task_by_dir_name(tasks_dir: Path, dir_name: str) -> Path | None:
"""Find an archived task directory with the exact active-task dir name."""
archive_dir = tasks_dir / DIR_ARCHIVE
if not archive_dir.is_dir():
return None
for month_dir in sorted(archive_dir.iterdir()):
if not month_dir.is_dir():
continue
candidate = month_dir / dir_name
if candidate.is_dir():
return candidate
return None
def _repo_relative_path(path: Path, repo_root: Path) -> str:
"""Format a path relative to the repo root when possible."""
try:
return path.relative_to(repo_root).as_posix()
except ValueError:
return str(path)
# =============================================================================
# Sub-agent platform detection + JSONL seeding
# =============================================================================
# Config directories of platforms that consume implement.jsonl / check.jsonl.
# Keep in sync with src/types/ai-tools.ts AI_TOOLS entries — these are the
# platforms listed in workflow.md's "agent-capable" Skill Routing block
# (Class-1 hook-inject + Class-2 pull-based preludes). Kilo / Antigravity /
# Devin are NOT in this list: they do not consume JSONL.
_SUBAGENT_CONFIG_DIRS: tuple[str, ...] = (
".claude",
".cursor",
".codex",
".kiro",
".gemini",
".opencode",
".qoder",
".codebuddy",
".factory", # Factory Droid
".github/copilot",
".pi", # Pi Agent
)
_SEED_EXAMPLE = (
"Fill with {\"file\": \"<path>\", \"reason\": \"<why>\"}. "
"Put spec/research files only — no code paths. "
"Run `python3 .trellis/scripts/get_context.py --mode packages` to list available specs. "
"Delete this line once real entries are added."
)
def _has_subagent_platform(repo_root: Path) -> bool:
"""Return True if any sub-agent-capable platform is configured.
Detected by probing well-known config directories at the repo root. Used
only to decide whether ``task.py create`` should seed empty
``implement.jsonl`` / ``check.jsonl`` files.
"""
for config_dir in _SUBAGENT_CONFIG_DIRS:
if (repo_root / config_dir).is_dir():
return True
return False
def _write_seed_jsonl(path: Path) -> None:
"""Write a one-line seed JSONL file with a self-describing ``_example``.
The seed row has no ``file`` field, so downstream consumers (hooks +
preludes) that iterate entries via ``item.get("file")`` naturally skip
it. The row exists purely as an in-file prompt for the AI curator.
"""
seed = {"_example": _SEED_EXAMPLE}
path.write_text(json.dumps(seed, ensure_ascii=False) + "\n", encoding="utf-8")
def _default_prd_content(title: str, description: str | None = None) -> str:
"""Return the default PRD skeleton created with every task."""
goal = (description or "").strip() or "TBD."
heading = title.strip() or "Untitled task"
return f"""# {heading}
## Goal
{goal}
## Requirements
- TBD
## Acceptance Criteria
- [ ] TBD
## Notes
- Keep `prd.md` focused on requirements, constraints, and acceptance criteria.
- Lightweight tasks can remain PRD-only.
- For complex tasks, add `design.md` for technical design and `implement.md` for execution planning before `task.py start`.
"""
# =============================================================================
# Command: create
# =============================================================================
def cmd_create(args: argparse.Namespace) -> int:
"""Create a new task."""
repo_root = get_repo_root()
if not args.title:
print(colored("Error: title is required", Colors.RED), file=sys.stderr)
return 1
# Validate --package (CLI source: fail-fast)
package: str | None = getattr(args, "package", None)
if not is_monorepo(repo_root):
# Single-repo: ignore --package, no package prefix
if package:
print(colored(f"Warning: --package ignored in single-repo project", Colors.YELLOW), file=sys.stderr)
package = None
elif package:
if not validate_package(package, repo_root):
packages = get_packages(repo_root)
available = ", ".join(sorted(packages.keys())) if packages else "(none)"
print(colored(f"Error: unknown package '{package}'. Available: {available}", Colors.RED), file=sys.stderr)
return 1
else:
# Inferred: default_package → None (no task.json yet for create)
package = resolve_package(repo_root=repo_root)
# Default assignee to current developer
assignee = args.assignee
if not assignee:
assignee = get_developer(repo_root)
if not assignee:
print(colored("Error: No developer set. Run init_developer.py first or use --assignee", Colors.RED), file=sys.stderr)
return 1
ensure_tasks_dir(repo_root)
# Get current developer as creator
creator = get_developer(repo_root) or assignee
# Generate slug if not provided
slug = args.slug or _slugify(args.title)
if not slug:
print(colored("Error: could not generate slug from title", Colors.RED), file=sys.stderr)
return 1
# Create task directory with MM-DD-slug format
tasks_dir = get_tasks_dir(repo_root)
date_prefix = generate_task_date_prefix()
dir_name = f"{date_prefix}-{slug}"
task_dir = tasks_dir / dir_name
task_json_path = task_dir / FILE_TASK_JSON
archived_task_dir = _find_archived_task_by_dir_name(tasks_dir, dir_name)
if archived_task_dir:
print(colored(f"Error: Task already archived: {dir_name}", Colors.RED), file=sys.stderr)
print(f"Archived at: {_repo_relative_path(archived_task_dir, repo_root)}", file=sys.stderr)
print("Use a new slug if you intend to create a new task.", file=sys.stderr)
return 1
if task_dir.exists():
print(colored(f"Warning: Task directory already exists: {dir_name}", Colors.YELLOW), file=sys.stderr)
else:
task_dir.mkdir(parents=True)
today = datetime.now().strftime("%Y-%m-%d")
# Record current branch as base_branch (PR target)
_, branch_out, _ = run_git(["branch", "--show-current"], cwd=repo_root)
current_branch = branch_out.strip() or "main"
task_data = {
"id": slug,
"name": slug,
"title": args.title,
"description": args.description or "",
"status": "planning",
"dev_type": None,
"scope": None,
"package": package,
"priority": args.priority,
"creator": creator,
"assignee": assignee,
"createdAt": today,
"completedAt": None,
"branch": None,
"base_branch": current_branch,
"worktree_path": None,
"commit": None,
"pr_url": None,
"subtasks": [],
"children": [],
"parent": None,
"relatedFiles": [],
"notes": "",
"meta": {},
}
write_json(task_json_path, task_data)
prd_path = task_dir / "prd.md"
if not prd_path.exists():
prd_path.write_text(
_default_prd_content(args.title, args.description),
encoding="utf-8",
)
# Seed implement.jsonl / check.jsonl for sub-agent-capable platforms.
# Agent curates real entries during planning when the task needs them.
# Agent-less platforms (Kilo / Antigravity / Devin) skip this — they
# load specs via the trellis-before-dev skill instead of JSONL.
seeded_jsonl = False
if _has_subagent_platform(repo_root):
for jsonl_name in ("implement.jsonl", "check.jsonl"):
jsonl_path = task_dir / jsonl_name
if not jsonl_path.exists():
_write_seed_jsonl(jsonl_path)
seeded_jsonl = True
# Handle --parent: establish bidirectional link
if args.parent:
parent_dir = resolve_task_dir(args.parent, repo_root)
parent_json_path = parent_dir / FILE_TASK_JSON
if not parent_json_path.is_file():
print(colored(f"Warning: Parent task.json not found: {args.parent}", Colors.YELLOW), file=sys.stderr)
else:
parent_data = read_json(parent_json_path)
if parent_data:
# Add child to parent's children list
parent_children = parent_data.get("children", [])
if dir_name not in parent_children:
parent_children.append(dir_name)
parent_data["children"] = parent_children
write_json(parent_json_path, parent_data)
# Set parent in child's task.json
task_data["parent"] = parent_dir.name
write_json(task_json_path, task_data)
print(colored(f"Linked as child of: {parent_dir.name}", Colors.GREEN), file=sys.stderr)
# Auto-activate the new task so the per-turn breadcrumb fires planning
# state. Best-effort: gracefully degrade if no session identity (CLI run
# outside an AI session) — the task is still created, the user can run
# task.py start later. Pointer is session-scoped so this never affects
# other AI sessions.
try:
from .active_task import resolve_context_key, set_active_task
if resolve_context_key():
try:
rel_dir = task_dir.relative_to(repo_root).as_posix()
except ValueError:
rel_dir = str(task_dir)
set_active_task(rel_dir, repo_root)
except Exception:
pass
print(colored(f"Created task: {dir_name}", Colors.GREEN), file=sys.stderr)
print("", file=sys.stderr)
print(colored("Next steps:", Colors.BLUE), file=sys.stderr)
print(" - Fill prd.md with requirements and acceptance criteria", file=sys.stderr)
print(" - Lightweight task: PRD-only is valid", file=sys.stderr)
print(" - Complex task: add design.md and implement.md before task.py start", file=sys.stderr)
if seeded_jsonl:
print(
" - Curate implement.jsonl / check.jsonl as spec/research manifests when sub-agents need context",
file=sys.stderr,
)
print(" - Use /trellis:continue or phase context to decide the next step", file=sys.stderr)
print("", file=sys.stderr)
# Output relative path for script chaining
print(f"{DIR_WORKFLOW}/{DIR_TASKS}/{dir_name}")
run_task_hooks("after_create", task_json_path, repo_root)
return 0
# =============================================================================
# Command: archive
# =============================================================================
def cmd_archive(args: argparse.Namespace) -> int:
"""Archive completed task."""
repo_root = get_repo_root()
task_name = args.name
if not task_name:
print(colored("Error: Task name is required", Colors.RED), file=sys.stderr)
return 1
tasks_dir = get_tasks_dir(repo_root)
# Resolve task directory (supports task name, relative path, or absolute path)
task_dir = resolve_task_dir(task_name, repo_root)
if not task_dir or not task_dir.is_dir():
print(colored(f"Error: Task not found: {task_name}", Colors.RED), file=sys.stderr)
print("Active tasks:", file=sys.stderr)
# Import lazily to avoid circular dependency
from .tasks import iter_active_tasks
for t in iter_active_tasks(tasks_dir):
print(f" - {t.dir_name}/", file=sys.stderr)
return 1
dir_name = task_dir.name
task_json_path = task_dir / FILE_TASK_JSON
# Update status before archiving
today = datetime.now().strftime("%Y-%m-%d")
# Names of child task dirs whose task.json gets modified below; passed
# into safe_archive_paths_to_add so they're staged in this commit.
modified_children: list[str] = []
if task_json_path.is_file():
data = read_json(task_json_path)
if data:
data["status"] = "completed"
data["completedAt"] = today
write_json(task_json_path, data)
# Handle subtask relationships on archive.
# Keep this task in its parent's children list so progress
# counters (children_progress) stay consistent — children
# missing from the active set are treated as completed.
task_children = data.get("children", [])
# If this is a parent, clear parent field in all children
if task_children:
for child_name in task_children:
child_dir_path = find_task_by_name(child_name, tasks_dir)
if child_dir_path:
child_json = child_dir_path / FILE_TASK_JSON
if child_json.is_file():
child_data = read_json(child_json)
if child_data:
child_data["parent"] = None
write_json(child_json, child_data)
modified_children.append(child_dir_path.name)
# Clear any session that still points at this task before the path moves.
from .active_task import clear_task_from_sessions
clear_task_from_sessions(str(task_dir), repo_root)
# Archive
result = archive_task_complete(task_dir, repo_root)
if "archived_to" in result:
archive_dest = Path(result["archived_to"])
year_month = archive_dest.parent.name
print(colored(f"Archived: {dir_name} -> archive/{year_month}/", Colors.GREEN), file=sys.stderr)
# Auto-commit unless --no-commit
if not getattr(args, "no_commit", False):
if not _auto_commit_archive(dir_name, repo_root, modified_children):
print(
colored(
"Archive moved on disk, but git auto-commit did not complete. "
"Resolve `git status` before continuing.",
Colors.RED,
),
file=sys.stderr,
)
return 1
# Return the archive path
print(f"{DIR_WORKFLOW}/{DIR_TASKS}/{DIR_ARCHIVE}/{year_month}/{dir_name}")
# Run hooks with the archived path
archived_json = archive_dest / FILE_TASK_JSON
run_task_hooks("after_archive", archived_json, repo_root)
return 0
return 1
def _auto_commit_archive(
task_name: str,
repo_root: Path,
modified_children: list[str] | None = None,
) -> bool:
"""Stage Trellis-owned task paths and commit after archive.
Scoped narrowly to the archived task's source + destination paths
plus any child task dirs whose ``task.json`` was edited (parent →
children relationship update). Dirty changes in OTHER active task
dirs are NOT bundled into the archive commit.
If ``.gitignore`` blocks the paths, we warn + skip — we do NOT
retry with ``git add -f``. The warning explicitly forbids
``git add -f .trellis/`` (which would fan out to caches/backups)
and points users at ``session_auto_commit: false``.
Honors ``session_auto_commit`` in ``.trellis/config.yaml``: when
set to ``false``, this function returns immediately without
touching git (the archive directory move on disk is unaffected).
"""
if not get_session_auto_commit(repo_root):
print(
"[OK] session_auto_commit: false — skipping git stage/commit.",
file=sys.stderr,
)
return True
source_rel = f"{DIR_WORKFLOW}/{DIR_TASKS}/{task_name}"
rc, tracked_out, _ = run_git(
["ls-files", "--", source_rel],
cwd=repo_root,
)
source_was_tracked = rc == 0 and bool(tracked_out.strip())
paths = safe_archive_paths_to_add(
repo_root, task_name=task_name, modified_children=modified_children
)
if not paths:
print("[OK] No task changes to commit.", file=sys.stderr)
return True
success, _, err = safe_git_add(paths, repo_root)
if not success:
if err and "ignored by" in err.lower():
print_gitignore_warning(paths)
else:
print(
f"[WARN] git add failed: {err.strip() if err else 'unknown error'}",
file=sys.stderr,
)
return not source_was_tracked
# Belt-and-suspenders for the phantom-delete bug: `safe_git_add` uses
# `git add` (no -A) which only stages additions/modifications. The
# source task directory was moved away by `shutil.move`, so its files
# need an explicit `git rm --cached` to stage the deletions in this
# same commit — otherwise they sit as uncommitted "phantom deletes"
# against HEAD until something later picks them up.
#
# `--ignore-unmatch` makes this a no-op when the task was never tracked
# (e.g. archiving a task that lived only in working tree).
run_git(
["rm", "-r", "--cached", "--ignore-unmatch", "--", source_rel],
cwd=repo_root,
)
rc, _, _ = run_git(
["diff", "--cached", "--quiet", "--", *paths, source_rel],
cwd=repo_root,
)
if rc == 0:
print("[OK] No task changes to commit.", file=sys.stderr)
return True
commit_msg = f"chore(task): archive {task_name}"
rc, _, err = run_git(["commit", "-m", commit_msg], cwd=repo_root)
if rc == 0:
print(f"[OK] Auto-committed: {commit_msg}", file=sys.stderr)
return True
else:
print(f"[WARN] Auto-commit failed: {err.strip()}", file=sys.stderr)
return not source_was_tracked
# =============================================================================
# Command: add-subtask
# =============================================================================
def cmd_add_subtask(args: argparse.Namespace) -> int:
"""Link a child task to a parent task."""
repo_root = get_repo_root()
parent_dir = resolve_task_dir(args.parent_dir, repo_root)
child_dir = resolve_task_dir(args.child_dir, repo_root)
parent_json_path = parent_dir / FILE_TASK_JSON
child_json_path = child_dir / FILE_TASK_JSON
if not parent_json_path.is_file():
print(colored(f"Error: Parent task.json not found: {args.parent_dir}", Colors.RED), file=sys.stderr)
return 1
if not child_json_path.is_file():
print(colored(f"Error: Child task.json not found: {args.child_dir}", Colors.RED), file=sys.stderr)
return 1
parent_data = read_json(parent_json_path)
child_data = read_json(child_json_path)
if not parent_data or not child_data:
print(colored("Error: Failed to read task.json", Colors.RED), file=sys.stderr)
return 1
# Check if child already has a parent
existing_parent = child_data.get("parent")
if existing_parent:
print(colored(f"Error: Child task already has a parent: {existing_parent}", Colors.RED), file=sys.stderr)
return 1
# Add child to parent's children list
parent_children = parent_data.get("children", [])
child_dir_name = child_dir.name
if child_dir_name not in parent_children:
parent_children.append(child_dir_name)
parent_data["children"] = parent_children
# Set parent in child's task.json
child_data["parent"] = parent_dir.name
# Write both
write_json(parent_json_path, parent_data)
write_json(child_json_path, child_data)
print(colored(f"Linked: {child_dir.name} -> {parent_dir.name}", Colors.GREEN), file=sys.stderr)
return 0
# =============================================================================
# Command: remove-subtask
# =============================================================================
def cmd_remove_subtask(args: argparse.Namespace) -> int:
"""Unlink a child task from a parent task."""
repo_root = get_repo_root()
parent_dir = resolve_task_dir(args.parent_dir, repo_root)
child_dir = resolve_task_dir(args.child_dir, repo_root)
parent_json_path = parent_dir / FILE_TASK_JSON
child_json_path = child_dir / FILE_TASK_JSON
if not parent_json_path.is_file():
print(colored(f"Error: Parent task.json not found: {args.parent_dir}", Colors.RED), file=sys.stderr)
return 1
if not child_json_path.is_file():
print(colored(f"Error: Child task.json not found: {args.child_dir}", Colors.RED), file=sys.stderr)
return 1
parent_data = read_json(parent_json_path)
child_data = read_json(child_json_path)
if not parent_data or not child_data:
print(colored("Error: Failed to read task.json", Colors.RED), file=sys.stderr)
return 1
# Remove child from parent's children list
parent_children = parent_data.get("children", [])
child_dir_name = child_dir.name
if child_dir_name in parent_children:
parent_children.remove(child_dir_name)
parent_data["children"] = parent_children
# Clear parent in child's task.json
child_data["parent"] = None
# Write both
write_json(parent_json_path, parent_data)
write_json(child_json_path, child_data)
print(colored(f"Unlinked: {child_dir.name} from {parent_dir.name}", Colors.GREEN), file=sys.stderr)
return 0
# =============================================================================
# Command: set-branch
# =============================================================================
def cmd_set_branch(args: argparse.Namespace) -> int:
"""Set git branch for task."""
repo_root = get_repo_root()
target_dir = resolve_task_dir(args.dir, repo_root)
branch = args.branch
if not branch:
print(colored("Error: Missing arguments", Colors.RED))
print("Usage: python3 task.py set-branch <task-dir> <branch-name>")
return 1
task_json = target_dir / FILE_TASK_JSON
if not task_json.is_file():
print(colored(f"Error: task.json not found at {target_dir}", Colors.RED))
return 1
data = read_json(task_json)
if not data:
return 1
data["branch"] = branch
write_json(task_json, data)
print(colored(f"✓ Branch set to: {branch}", Colors.GREEN))
return 0
# =============================================================================
# Command: set-base-branch
# =============================================================================
def cmd_set_base_branch(args: argparse.Namespace) -> int:
"""Set the base branch (PR target) for task."""
repo_root = get_repo_root()
target_dir = resolve_task_dir(args.dir, repo_root)
base_branch = args.base_branch
if not base_branch:
print(colored("Error: Missing arguments", Colors.RED))
print("Usage: python3 task.py set-base-branch <task-dir> <base-branch>")
print("Example: python3 task.py set-base-branch <dir> develop")
print()
print("This sets the target branch for PR (the branch your feature will merge into).")
return 1
task_json = target_dir / FILE_TASK_JSON
if not task_json.is_file():
print(colored(f"Error: task.json not found at {target_dir}", Colors.RED))
return 1
data = read_json(task_json)
if not data:
return 1
data["base_branch"] = base_branch
write_json(task_json, data)
print(colored(f"✓ Base branch set to: {base_branch}", Colors.GREEN))
print(f" PR will target: {base_branch}")
return 0
# =============================================================================
# Command: set-scope
# =============================================================================
def cmd_set_scope(args: argparse.Namespace) -> int:
"""Set scope for PR title."""
repo_root = get_repo_root()
target_dir = resolve_task_dir(args.dir, repo_root)
scope = args.scope
if not scope:
print(colored("Error: Missing arguments", Colors.RED))
print("Usage: python3 task.py set-scope <task-dir> <scope>")
return 1
task_json = target_dir / FILE_TASK_JSON
if not task_json.is_file():
print(colored(f"Error: task.json not found at {target_dir}", Colors.RED))
return 1
data = read_json(task_json)
if not data:
return 1
data["scope"] = scope
write_json(task_json, data)
print(colored(f"✓ Scope set to: {scope}", Colors.GREEN))
return 0
.trellis/scripts/common/task_utils.py
Executable
+274
View File
@@ -0,0 +1,274 @@
#!/usr/bin/env python3
"""
Task utility functions.
Provides:
is_safe_task_path - Validate task path is safe to operate on
find_task_by_name - Find task directory by name
resolve_task_dir - Resolve task directory from name, relative, or absolute path
archive_task_dir - Archive task to monthly directory
run_task_hooks - Run lifecycle hooks for task events
"""
from __future__ import annotations
import shutil
import sys
from datetime import datetime
from pathlib import Path
from .paths import get_repo_root, get_tasks_dir
# =============================================================================
# Path Safety
# =============================================================================
def is_safe_task_path(task_path: str, repo_root: Path | None = None) -> bool:
"""Check if a relative task path is safe to operate on.
Args:
task_path: Task path (relative to repo_root).
repo_root: Repository root path. Defaults to auto-detected.
Returns:
True if safe, False if dangerous.
"""
if repo_root is None:
repo_root = get_repo_root()
normalized = task_path.replace("\\", "/")
# Check empty or null
if not normalized or normalized == "null":
print("Error: empty or null task path", file=sys.stderr)
return False
# Reject absolute paths
if Path(task_path).is_absolute():
print(f"Error: absolute path not allowed: {task_path}", file=sys.stderr)
return False
# Reject ".", "..", paths starting with "./" or "../", or containing ".."
if normalized in (".", "..") or normalized.startswith("./") or normalized.startswith("../") or ".." in normalized:
print(f"Error: path traversal not allowed: {task_path}", file=sys.stderr)
return False
# Final check: ensure resolved path is not the repo root
abs_path = repo_root / Path(normalized)
if abs_path.exists():
try:
resolved = abs_path.resolve()
root_resolved = repo_root.resolve()
if resolved == root_resolved:
print(f"Error: path resolves to repo root: {task_path}", file=sys.stderr)
return False
except (OSError, IOError):
pass
return True
# =============================================================================
# Task Lookup
# =============================================================================
def find_task_by_name(task_name: str, tasks_dir: Path) -> Path | None:
"""Find task directory by name (exact or suffix match).
Args:
task_name: Task name to find.
tasks_dir: Tasks directory path.
Returns:
Absolute path to task directory, or None if not found.
"""
if not task_name or not tasks_dir or not tasks_dir.is_dir():
return None
# Try exact match first
exact_match = tasks_dir / task_name
if exact_match.is_dir():
return exact_match
# Try suffix match (e.g., "my-task" matches "01-21-my-task")
for d in tasks_dir.iterdir():
if d.is_dir() and d.name.endswith(f"-{task_name}"):
return d
return None
# =============================================================================
# Archive Operations
# =============================================================================
def archive_task_dir(task_dir_abs: Path, repo_root: Path | None = None) -> Path | None:
"""Archive a task directory to archive/{YYYY-MM}/.
Args:
task_dir_abs: Absolute path to task directory.
repo_root: Repository root path. Defaults to auto-detected.
Returns:
Path to archived directory, or None on error.
"""
if not task_dir_abs.is_dir():
print(f"Error: task directory not found: {task_dir_abs}", file=sys.stderr)
return None
# Get tasks directory (parent of the task)
tasks_dir = task_dir_abs.parent
archive_dir = tasks_dir / "archive"
year_month = datetime.now().strftime("%Y-%m")
month_dir = archive_dir / year_month
# Create archive directory
try:
month_dir.mkdir(parents=True, exist_ok=True)
except (OSError, IOError) as e:
print(f"Error: Failed to create archive directory: {e}", file=sys.stderr)
return None
# Move task to archive
task_name = task_dir_abs.name
dest = month_dir / task_name
try:
shutil.move(str(task_dir_abs), str(dest))
except (OSError, IOError, shutil.Error) as e:
print(f"Error: Failed to move task to archive: {e}", file=sys.stderr)
return None
return dest
def archive_task_complete(
task_dir_abs: Path,
repo_root: Path | None = None
) -> dict[str, str]:
"""Complete archive workflow: archive directory.
Args:
task_dir_abs: Absolute path to task directory.
repo_root: Repository root path. Defaults to auto-detected.
Returns:
Dict with archive result info.
"""
if not task_dir_abs.is_dir():
print(f"Error: task directory not found: {task_dir_abs}", file=sys.stderr)
return {}
archive_dest = archive_task_dir(task_dir_abs, repo_root)
if archive_dest:
return {"archived_to": str(archive_dest)}
return {}
# =============================================================================
# Task Directory Resolution
# =============================================================================
def resolve_task_dir(target_dir: str, repo_root: Path) -> Path:
"""Resolve task directory to absolute path.
Supports:
- Absolute path: /path/to/task
- Relative path: .trellis/tasks/01-31-my-task
- Task name: my-task (uses find_task_by_name for lookup)
Args:
target_dir: Task directory specification.
repo_root: Repository root path.
Returns:
Resolved absolute path.
"""
if not target_dir:
return Path()
normalized = target_dir.replace("\\", "/")
while normalized.startswith("./"):
normalized = normalized[2:]
# Absolute path
if Path(target_dir).is_absolute():
return Path(target_dir)
# Relative path (contains path separator or starts with .trellis)
if "/" in normalized or normalized.startswith(".trellis"):
return repo_root / Path(normalized)
# Task name - try to find in tasks directory
tasks_dir = get_tasks_dir(repo_root)
found = find_task_by_name(target_dir, tasks_dir)
if found:
return found
# Fallback to treating as relative path
return repo_root / Path(normalized)
# =============================================================================
# Lifecycle Hooks
# =============================================================================
def run_task_hooks(event: str, task_json_path: Path, repo_root: Path) -> None:
"""Run lifecycle hooks for a task event.
Args:
event: Event name (e.g. "after_create").
task_json_path: Absolute path to the task's task.json.
repo_root: Repository root for cwd and config lookup.
"""
import os
import subprocess
from .config import get_hooks
from .log import Colors, colored
commands = get_hooks(event, repo_root)
if not commands:
return
env = {**os.environ, "TASK_JSON_PATH": str(task_json_path)}
for cmd in commands:
try:
result = subprocess.run(
cmd,
shell=True,
cwd=repo_root,
env=env,
capture_output=True,
text=True,
encoding="utf-8",
errors="replace",
)
if result.returncode != 0:
print(
colored(f"[WARN] Hook failed ({event}): {cmd}", Colors.YELLOW),
file=sys.stderr,
)
if result.stderr.strip():
print(f" {result.stderr.strip()}", file=sys.stderr)
except Exception as e:
print(
colored(f"[WARN] Hook error ({event}): {cmd} — {e}", Colors.YELLOW),
file=sys.stderr,
)
# =============================================================================
# Main Entry (for testing)
# =============================================================================
if __name__ == "__main__":
repo = get_repo_root()
tasks = get_tasks_dir(repo)
print(f"Tasks dir: {tasks}")
print(f"is_safe_task_path('.trellis/tasks/test'): {is_safe_task_path('.trellis/tasks/test', repo)}")
print(f"is_safe_task_path('../test'): {is_safe_task_path('../test', repo)}")
.trellis/scripts/common/tasks.py
Executable
+112
View File
@@ -0,0 +1,112 @@
"""
Task data access layer.
Single source of truth for loading and iterating task directories.
Replaces scattered task.json parsing across 9+ files.
Provides:
load_task — Load a single task by directory path
iter_active_tasks — Iterate all non-archived tasks (sorted)
get_all_statuses — Get {dir_name: status} map for children progress
"""
from __future__ import annotations
from collections.abc import Iterator
from pathlib import Path
from .io import read_json
from .paths import FILE_TASK_JSON
from .types import TaskInfo
def load_task(task_dir: Path) -> TaskInfo | None:
"""Load task from a directory containing task.json.
Args:
task_dir: Absolute path to the task directory.
Returns:
TaskInfo if task.json exists and is valid, None otherwise.
"""
task_json = task_dir / FILE_TASK_JSON
if not task_json.is_file():
return None
data = read_json(task_json)
if not data:
return None
return TaskInfo(
dir_name=task_dir.name,
directory=task_dir,
title=data.get("title") or data.get("name") or "unknown",
status=data.get("status", "unknown"),
assignee=data.get("assignee", ""),
priority=data.get("priority", "P2"),
children=tuple(data.get("children", [])),
parent=data.get("parent"),
package=data.get("package"),
raw=data,
)
def iter_active_tasks(tasks_dir: Path) -> Iterator[TaskInfo]:
"""Iterate all active (non-archived) tasks, sorted by directory name.
Skips the "archive" directory and directories without valid task.json.
Args:
tasks_dir: Path to the tasks directory.
Yields:
TaskInfo for each valid task.
"""
if not tasks_dir.is_dir():
return
for d in sorted(tasks_dir.iterdir()):
if not d.is_dir() or d.name == "archive":
continue
info = load_task(d)
if info is not None:
yield info
def get_all_statuses(tasks_dir: Path) -> dict[str, str]:
"""Get a {dir_name: status} mapping for all active tasks.
Useful for computing children progress without loading full TaskInfo.
Args:
tasks_dir: Path to the tasks directory.
Returns:
Dict mapping directory names to status strings.
"""
return {t.dir_name: t.status for t in iter_active_tasks(tasks_dir)}
def children_progress(
children: tuple[str, ...] | list[str],
all_statuses: dict[str, str],
) -> str:
"""Format children progress string like " [2/3 done]".
Args:
children: List of child directory names.
all_statuses: Status map from get_all_statuses().
Returns:
Formatted string, or "" if no children.
"""
if not children:
return ""
# A child missing from active statuses has been archived (cmd_archive
# sets status=completed before moving the dir). Count it as done so
# parent progress doesn't regress when children are archived.
done = sum(
1 for c in children
if c not in all_statuses or all_statuses.get(c) in ("completed", "done")
)
return f" [{done}/{len(children)} done]"
.trellis/scripts/common/trellis_config.py
Executable
+131
View File
@@ -0,0 +1,131 @@
#!/usr/bin/env python3
"""
Standalone reader for .trellis/config.yaml.
Mirrors a minimal subset of common.config so callers (hooks, workflow_phase)
can read configuration without importing the full task/repo helpers. Returns
an empty dict on missing/malformed files so callers stay simple.
"""
from __future__ import annotations
from pathlib import Path
from typing import Optional
CONFIG_REL_PATH = ".trellis/config.yaml"
def _unquote(value: str) -> str:
if len(value) >= 2 and value[0] == value[-1] and value[0] in ('"', "'"):
return value[1:-1]
return value
def _strip_inline_comment(value: str) -> str:
"""Strip ` # …` inline comments while preserving `#` inside quoted strings.
YAML treats ` #` (space-hash) as a comment opener; bare `#` inside a token
is part of the value. Quoted strings are immune.
"""
in_quote: str | None = None
for idx, ch in enumerate(value):
if in_quote:
if ch == in_quote:
in_quote = None
continue
if ch in ('"', "'"):
in_quote = ch
continue
if ch == "#" and (idx == 0 or value[idx - 1].isspace()):
return value[:idx]
return value
def _next_content_line(lines: list[str], start: int) -> tuple[int, str]:
i = start
while i < len(lines):
stripped = lines[i].strip()
if stripped and not stripped.startswith("#"):
return i, lines[i]
i += 1
return i, ""
def _parse_yaml_block(
lines: list[str], start: int, min_indent: int, target: dict
) -> int:
i = start
current_list: list | None = None
while i < len(lines):
line = lines[i]
stripped = line.strip()
if not stripped or stripped.startswith("#"):
i += 1
continue
indent = len(line) - len(line.lstrip())
if indent < min_indent:
break
if stripped.startswith("- "):
if current_list is not None:
current_list.append(_unquote(stripped[2:].strip()))
i += 1
elif ":" in stripped:
key, _, value = stripped.partition(":")
key = key.strip()
value = _strip_inline_comment(value).strip()
value = _unquote(value)
current_list = None
if value:
target[key] = value
i += 1
else:
next_i, next_line = _next_content_line(lines, i + 1)
if next_i >= len(lines):
target[key] = {}
i = next_i
elif next_line.strip().startswith("- "):
current_list = []
target[key] = current_list
i += 1
else:
next_indent = len(next_line) - len(next_line.lstrip())
if next_indent > indent:
nested: dict = {}
target[key] = nested
i = _parse_yaml_block(lines, i + 1, next_indent, nested)
else:
target[key] = {}
i += 1
else:
i += 1
return i
def parse_simple_yaml(content: str) -> dict:
"""Parse a small subset of YAML. See common.config for full doc."""
lines = content.splitlines()
result: dict = {}
_parse_yaml_block(lines, 0, 0, result)
return result
def read_trellis_config(repo_root: Optional[Path] = None) -> dict:
"""Read .trellis/config.yaml. Returns {} on missing or malformed file."""
root = repo_root or Path.cwd()
config_file = root / CONFIG_REL_PATH
try:
content = config_file.read_text(encoding="utf-8")
except (FileNotFoundError, OSError):
return {}
try:
parsed = parse_simple_yaml(content)
except Exception:
return {}
return parsed if isinstance(parsed, dict) else {}
.trellis/scripts/common/types.py
Executable
+110
View File
@@ -0,0 +1,110 @@
"""
Core type definitions for Trellis task data.
Provides:
TaskData — TypedDict for task.json shape (read-path type hints only)
TaskInfo — Frozen dataclass for loaded task (the public API type)
AgentRecord — TypedDict for registry.json agent entries
"""
from __future__ import annotations
from dataclasses import dataclass
from pathlib import Path
from typing import TypedDict
# =============================================================================
# task.json shape (TypedDict — used only for read-path type hints)
# =============================================================================
class TaskData(TypedDict, total=False):
"""Shape of task.json on disk.
Used only for type annotations when reading task.json.
Writes must use the original dict to avoid losing unknown fields.
"""
id: str
name: str
title: str
description: str
status: str
dev_type: str
scope: str | None
package: str | None
priority: str
creator: str
assignee: str
createdAt: str
completedAt: str | None
branch: str | None
base_branch: str | None
worktree_path: str | None
commit: str | None
pr_url: str | None
subtasks: list[str]
children: list[str]
parent: str | None
relatedFiles: list[str]
notes: str
meta: dict
# =============================================================================
# Loaded task object (frozen dataclass — the public API type)
# =============================================================================
@dataclass(frozen=True)
class TaskInfo:
"""Immutable view of a loaded task.
Created by load_task() / iter_active_tasks().
Contains the commonly accessed fields; the original dict
is preserved in `raw` for write-back and uncommon field access.
"""
dir_name: str
directory: Path
title: str
status: str
assignee: str
priority: str
children: tuple[str, ...]
parent: str | None
package: str | None
raw: dict # original dict — use for writes and uncommon fields
@property
def name(self) -> str:
"""Task name (id or name field)."""
return self.raw.get("name") or self.raw.get("id") or self.dir_name
@property
def description(self) -> str:
return self.raw.get("description", "")
@property
def branch(self) -> str | None:
return self.raw.get("branch")
@property
def meta(self) -> dict:
return self.raw.get("meta", {})
# =============================================================================
# registry.json agent entry
# =============================================================================
class AgentRecord(TypedDict, total=False):
"""Shape of an agent entry in registry.json."""
id: str
pid: int
task_dir: str
worktree_path: str
branch: str
platform: str
started_at: str
status: str
.trellis/scripts/common/workflow_phase.py
Executable
+212
View File
@@ -0,0 +1,212 @@
#!/usr/bin/env python3
# -*- coding: utf-8 -*-
"""
Workflow Phase Extraction.
Extracts step-level content from .trellis/workflow.md and optionally filters
platform-specific blocks.
Platform marker syntax in workflow.md:
[Claude Code, Cursor, ...]
agent-capable content
[/Claude Code, Cursor, ...]
Provides:
get_phase_index - Extract the Phase Index section (no --step)
get_step - Extract a single step (#### X.X) section
filter_platform - Strip platform blocks that don't include the given name
"""
from __future__ import annotations
import re
from .paths import DIR_WORKFLOW, get_repo_root
def _workflow_md_path():
return get_repo_root() / DIR_WORKFLOW / "workflow.md"
# Match a line that *is* a platform marker: "[A, B, C]" or "[/A, B, C]"
_MARKER_RE = re.compile(r"^\[(/?)([A-Za-z][^\[\]]*)\]\s*$")
# Step heading: "#### 1.0 Title" or "#### 1.0 ..."
_STEP_HEADING_RE = re.compile(r"^####\s+(\d+\.\d+)\b.*$")
# Phase Index starts here; Phase 1/2/3 step bodies follow; ends at Breadcrumbs.
_PHASE_INDEX_HEADING = "## Phase Index"
def _read_workflow() -> str:
path = _workflow_md_path()
if not path.exists():
raise FileNotFoundError(f"workflow.md not found: {path}")
return path.read_text(encoding="utf-8")
def _parse_marker(line: str) -> tuple[bool, list[str]] | None:
"""Parse a platform marker line.
Returns:
(is_closing, [platform_names]) if line is a marker, else None.
"""
m = _MARKER_RE.match(line)
if not m:
return None
is_closing = m.group(1) == "/"
names = [p.strip() for p in m.group(2).split(",") if p.strip()]
return is_closing, names
def get_phase_index() -> str:
"""Return the compact Phase Index summary from workflow.md.
SessionStart and no-step phase context use this small summary as their
orientation payload. Detailed Phase 1/2/3 instructions are loaded with
``get_step`` on demand. ``[workflow-state:STATUS]`` tag blocks are
consumed by the per-turn hook, so they're stripped from this output.
"""
text = _read_workflow()
lines = text.splitlines()
start: int | None = None
end: int | None = None
for i, line in enumerate(lines):
stripped = line.strip()
if start is None and stripped == _PHASE_INDEX_HEADING:
start = i
continue
if start is not None and stripped == "## Phase 1: Plan":
end = i
break
if start is None:
return ""
if end is None:
end = len(lines)
section = "\n".join(lines[start:end]).rstrip()
# Strip [workflow-state:STATUS]...[/workflow-state:STATUS] blocks since
# they're injected separately by inject-workflow-state.py per-turn.
import re as _re
tag_re = _re.compile(
r"\[workflow-state:([A-Za-z0-9_-]+)\]\s*\n.*?\n\s*\[/workflow-state:\1\]\n?",
_re.DOTALL,
)
return tag_re.sub("", section).rstrip() + "\n"
def get_step(step_id: str) -> str:
"""Return the `#### X.X` section matching step_id (header + body).
Body ends at the next `####` or `---` or `##` heading (whichever comes first).
"""
text = _read_workflow()
lines = text.splitlines()
start: int | None = None
for i, line in enumerate(lines):
m = _STEP_HEADING_RE.match(line)
if m and m.group(1) == step_id:
start = i
break
if start is None:
return ""
end: int = len(lines)
for j in range(start + 1, len(lines)):
line = lines[j]
if line.startswith("#### "):
end = j
break
if line.startswith("## "):
end = j
break
# Horizontal rule at column 0
if line.strip() == "---":
end = j
break
return "\n".join(lines[start:end]).rstrip() + "\n"
def _platform_matches(platform: str, block_names: list[str]) -> bool:
"""Case-insensitive fuzzy match: accept 'cursor', 'Cursor', 'claude-code', 'Claude Code'."""
needle = platform.lower().replace("-", "").replace("_", "").replace(" ", "")
for name in block_names:
hay = name.lower().replace("-", "").replace("_", "").replace(" ", "")
if needle == hay:
return True
return False
def resolve_effective_platform(platform: str, config: dict) -> str:
"""Map ``codex`` to a dispatch-mode-namespaced virtual platform name.
When ``--platform codex`` is passed, return ``"codex-inline"`` (default)
or ``"codex-sub-agent"`` based on ``.trellis/config.yaml`` ``codex.dispatch_mode``.
``filter_platform`` then surfaces blocks whose marker lists include the
namespaced name (e.g. ``[codex-sub-agent, ...]`` or ``[codex-inline, Kilo,
Antigravity, Devin]``).
Default is ``inline`` because Codex sub-agents run with ``fork_turns="none"``
isolation and can't inherit the parent session's task context — inline
keeps the main agent in charge so context isn't lost. Invalid / missing
values also fall back to inline.
Other platforms are returned unchanged.
"""
if platform == "codex":
mode = "inline"
codex_cfg = config.get("codex") if isinstance(config, dict) else None
if isinstance(codex_cfg, dict):
cfg_mode = codex_cfg.get("dispatch_mode")
if cfg_mode in ("inline", "sub-agent"):
mode = cfg_mode
return f"codex-{mode}"
return platform
def filter_platform(content: str, platform: str) -> str:
"""Keep lines outside any `[...]` block + lines inside blocks that include platform.
Marker lines themselves are dropped from the output.
"""
lines = content.splitlines()
out: list[str] = []
in_block = False
keep_block = False
for line in lines:
marker = _parse_marker(line)
if marker is not None:
is_closing, names = marker
if not is_closing:
in_block = True
keep_block = _platform_matches(platform, names)
else:
in_block = False
keep_block = False
continue # drop the marker line itself
if in_block:
if keep_block:
out.append(line)
continue
out.append(line)
# Collapse runs of 3+ blank lines that may arise from dropped markers
collapsed: list[str] = []
blank_run = 0
for line in out:
if line.strip() == "":
blank_run += 1
if blank_run <= 2:
collapsed.append(line)
else:
blank_run = 0
collapsed.append(line)
return "\n".join(collapsed).rstrip() + "\n"
.trellis/scripts/get_context.py
Executable
+16
View File
@@ -0,0 +1,16 @@
#!/usr/bin/env python3
"""
Get Session Context for AI Agent.
Usage:
python3 get_context.py Output context in text format
python3 get_context.py --json Output context in JSON format
"""
from __future__ import annotations
from common.git_context import main
if __name__ == "__main__":
main()
.trellis/scripts/get_developer.py
Executable
+26
View File
@@ -0,0 +1,26 @@
#!/usr/bin/env python3
"""
Get current developer name.
This is a wrapper that uses common/paths.py
"""
from __future__ import annotations
import sys
from common.paths import get_developer
def main() -> None:
"""CLI entry point."""
developer = get_developer()
if developer:
print(developer)
else:
print("Developer not initialized", file=sys.stderr)
sys.exit(1)
if __name__ == "__main__":
main()
.trellis/scripts/hooks/linear_sync.py
Executable
+243
View File
@@ -0,0 +1,243 @@
#!/usr/bin/env python3
"""Linear sync hook for Trellis task lifecycle.
Syncs task events to Linear via the `linearis` CLI.
Usage (called automatically by task.py hooks):
python3 .trellis/scripts/hooks/linear_sync.py create
python3 .trellis/scripts/hooks/linear_sync.py start
python3 .trellis/scripts/hooks/linear_sync.py archive
Manual usage:
TASK_JSON_PATH=.trellis/tasks/<name>/task.json python3 .trellis/scripts/hooks/linear_sync.py sync
Environment:
TASK_JSON_PATH - Absolute path to task.json (set by task.py)
Configuration:
.trellis/hooks.local.json - Local config (gitignored), example:
{
"linear": {
"team": "TEAM_KEY",
"project": "Project Name",
"assignees": {
"dev-name": "linear-user-id"
}
}
}
"""
from __future__ import annotations
import json
import os
import subprocess
import sys
from pathlib import Path
# ─── Configuration ────────────────────────────────────────────────────────────
# Trellis priority → Linear priority (1=Urgent, 2=High, 3=Medium, 4=Low)
PRIORITY_MAP = {"P0": 1, "P1": 2, "P2": 3, "P3": 4}
# Linear status names (must match your team's workflow)
STATUS_IN_PROGRESS = "In Progress"
STATUS_DONE = "Done"
def _load_config() -> dict:
"""Load local hook config from .trellis/hooks.local.json."""
task_json_path = os.environ.get("TASK_JSON_PATH", "")
if task_json_path:
# Walk up from task.json to find .trellis/
trellis_dir = Path(task_json_path).parent.parent.parent
else:
trellis_dir = Path(".trellis")
config_path = trellis_dir / "hooks.local.json"
try:
with open(config_path, encoding="utf-8") as f:
return json.load(f)
except (OSError, json.JSONDecodeError):
return {}
CONFIG = _load_config()
LINEAR_CFG = CONFIG.get("linear", {})
TEAM = LINEAR_CFG.get("team", "")
PROJECT = LINEAR_CFG.get("project", "")
ASSIGNEE_MAP = LINEAR_CFG.get("assignees", {})
# ─── Helpers ──────────────────────────────────────────────────────────────────
def _read_task() -> tuple[dict, str]:
path = os.environ.get("TASK_JSON_PATH", "")
if not path:
print("TASK_JSON_PATH not set", file=sys.stderr)
sys.exit(1)
with open(path, encoding="utf-8") as f:
return json.load(f), path
def _write_task(data: dict, path: str) -> None:
with open(path, "w", encoding="utf-8") as f:
json.dump(data, f, indent=2, ensure_ascii=False)
f.write("\n")
def _linearis(*args: str) -> dict | None:
result = subprocess.run(
["linearis", *args],
capture_output=True,
text=True,
encoding="utf-8",
errors="replace",
)
if result.returncode != 0:
print(f"linearis error: {result.stderr.strip()}", file=sys.stderr)
sys.exit(1)
stdout = result.stdout.strip()
if stdout:
return json.loads(stdout)
return None
def _get_linear_issue(task: dict) -> str | None:
meta = task.get("meta")
if isinstance(meta, dict):
return meta.get("linear_issue")
return None
# ─── Actions ──────────────────────────────────────────────────────────────────
def cmd_create() -> None:
if not TEAM:
print("No linear.team configured in hooks.local.json", file=sys.stderr)
sys.exit(1)
task, path = _read_task()
# Skip if already linked
if _get_linear_issue(task):
print(f"Already linked: {_get_linear_issue(task)}")
return
title = task.get("title") or task.get("name") or "Untitled"
args = ["issues", "create", title, "--team", TEAM]
# Map priority
priority = PRIORITY_MAP.get(task.get("priority", ""), 0)
if priority:
args.extend(["-p", str(priority)])
# Set project
if PROJECT:
args.extend(["--project", PROJECT])
# Assign to Linear user
assignee = task.get("assignee", "")
linear_user_id = ASSIGNEE_MAP.get(assignee)
if linear_user_id:
args.extend(["--assignee", linear_user_id])
# Link to parent's Linear issue if available
parent_issue = _resolve_parent_linear_issue(task)
if parent_issue:
args.extend(["--parent-ticket", parent_issue])
result = _linearis(*args)
if result and "identifier" in result:
if not isinstance(task.get("meta"), dict):
task["meta"] = {}
task["meta"]["linear_issue"] = result["identifier"]
_write_task(task, path)
print(f"Created Linear issue: {result['identifier']}")
def cmd_start() -> None:
task, _ = _read_task()
issue = _get_linear_issue(task)
if not issue:
return
_linearis("issues", "update", issue, "-s", STATUS_IN_PROGRESS)
print(f"Updated {issue} -> {STATUS_IN_PROGRESS}")
cmd_sync()
def cmd_archive() -> None:
task, _ = _read_task()
issue = _get_linear_issue(task)
if not issue:
return
_linearis("issues", "update", issue, "-s", STATUS_DONE)
print(f"Updated {issue} -> {STATUS_DONE}")
def cmd_sync() -> None:
"""Sync prd.md content to Linear issue description."""
task, _ = _read_task()
issue = _get_linear_issue(task)
if not issue:
print("No linear_issue in meta, run create first", file=sys.stderr)
sys.exit(1)
# Find prd.md next to task.json
task_json_path = os.environ.get("TASK_JSON_PATH", "")
prd_path = Path(task_json_path).parent / "prd.md"
if not prd_path.is_file():
print(f"No prd.md found at {prd_path}", file=sys.stderr)
sys.exit(1)
description = prd_path.read_text(encoding="utf-8").strip()
_linearis("issues", "update", issue, "-d", description)
print(f"Synced prd.md to {issue} description")
# ─── Parent Issue Resolution ─────────────────────────────────────────────────
def _resolve_parent_linear_issue(task: dict) -> str | None:
"""Find parent task's Linear issue identifier."""
parent_name = task.get("parent")
if not parent_name:
return None
task_json_path = os.environ.get("TASK_JSON_PATH", "")
if not task_json_path:
return None
current_task_dir = Path(task_json_path).parent
tasks_dir = current_task_dir.parent
parent_json = tasks_dir / parent_name / "task.json"
if parent_json.exists():
try:
with open(parent_json, encoding="utf-8") as f:
parent_task = json.load(f)
return _get_linear_issue(parent_task)
except (json.JSONDecodeError, OSError):
pass
return None
# ─── Main ─────────────────────────────────────────────────────────────────────
if __name__ == "__main__":
action = sys.argv[1] if len(sys.argv) > 1 else ""
actions = {
"create": cmd_create,
"start": cmd_start,
"archive": cmd_archive,
"sync": cmd_sync,
}
fn = actions.get(action)
if fn:
fn()
else:
print(f"Unknown action: {action}", file=sys.stderr)
print(f"Valid actions: {', '.join(actions)}", file=sys.stderr)
sys.exit(1)
.trellis/scripts/init_developer.py
Executable
+51
View File
@@ -0,0 +1,51 @@
#!/usr/bin/env python3
"""
Initialize developer for workflow.
Usage:
python3 init_developer.py <developer-name>
This creates:
- .trellis/.developer file with developer info
- .trellis/workspace/<name>/ directory structure
"""
from __future__ import annotations
import sys
from common.paths import (
DIR_WORKFLOW,
FILE_DEVELOPER,
get_developer,
)
from common.developer import init_developer
def main() -> None:
"""CLI entry point."""
if len(sys.argv) < 2:
print(f"Usage: {sys.argv[0]} <developer-name>")
print()
print("Example:")
print(f" {sys.argv[0]} john")
sys.exit(1)
name = sys.argv[1]
# Check if already initialized
existing = get_developer()
if existing:
print(f"Developer already initialized: {existing}")
print()
print(f"To reinitialize, remove {DIR_WORKFLOW}/{FILE_DEVELOPER} first")
sys.exit(0)
if init_developer(name):
sys.exit(0)
else:
sys.exit(1)
if __name__ == "__main__":
main()
.trellis/scripts/task.py
Executable
+500
View File
@@ -0,0 +1,500 @@
#!/usr/bin/env python3
# -*- coding: utf-8 -*-
"""
Task Management Script.
Usage:
python3 task.py create "<title>" [--slug <name>] [--assignee <dev>] [--priority P0|P1|P2|P3] [--parent <dir>] [--package <pkg>]
python3 task.py add-context <dir> <file> <path> [reason] # Add jsonl entry
python3 task.py validate <dir> # Validate jsonl files
python3 task.py list-context <dir> # List jsonl entries
python3 task.py start <dir> # Set active task
python3 task.py current [--source] # Show active task
python3 task.py finish # Clear active task
python3 task.py set-branch <dir> <branch> # Set git branch
python3 task.py set-base-branch <dir> <branch> # Set PR target branch
python3 task.py set-scope <dir> <scope> # Set scope for PR title
python3 task.py archive <task-dir> # Archive completed task
python3 task.py list # List active tasks
python3 task.py list-archive [month] # List archived tasks
python3 task.py add-subtask <parent-dir> <child-dir> # Link child to parent
python3 task.py remove-subtask <parent-dir> <child-dir> # Unlink child from parent
"""
from __future__ import annotations
import argparse
import sys
from common.log import Colors, colored
from common.paths import (
DIR_WORKFLOW,
DIR_TASKS,
FILE_TASK_JSON,
get_repo_root,
get_developer,
get_tasks_dir,
get_current_task,
)
from common.active_task import (
clear_active_task,
resolve_active_task,
resolve_context_key,
set_active_task,
)
from common.io import read_json, write_json
from common.task_utils import resolve_task_dir, run_task_hooks
from common.tasks import iter_active_tasks, children_progress
# Import command handlers from split modules (also re-exports for plan.py compatibility)
from common.task_store import (
cmd_create,
cmd_archive,
cmd_set_branch,
cmd_set_base_branch,
cmd_set_scope,
cmd_add_subtask,
cmd_remove_subtask,
)
from common.task_context import (
cmd_add_context,
cmd_validate,
cmd_list_context,
)
# =============================================================================
# Command: start / finish
# =============================================================================
def cmd_start(args: argparse.Namespace) -> int:
"""Set active task."""
repo_root = get_repo_root()
task_input = args.dir
if not task_input:
print(colored("Error: task directory or name required", Colors.RED))
return 1
# Resolve task directory (supports task name, relative path, or absolute path)
full_path = resolve_task_dir(task_input, repo_root)
if not full_path.is_dir():
print(colored(f"Error: Task not found: {task_input}", Colors.RED))
print("Hint: Use task name (e.g., 'my-task') or full path (e.g., '.trellis/tasks/01-31-my-task')")
return 1
# Convert to relative path for storage
try:
task_dir = full_path.relative_to(repo_root).as_posix()
except ValueError:
task_dir = str(full_path)
task_json_path = full_path / FILE_TASK_JSON
if not resolve_context_key():
# Degraded mode: no session identity available.
# Hook didn't inject TRELLIS_CONTEXT_ID (common on Windows + Claude Code,
# --continue resume path, fork distribution, hooks disabled, etc.). Skip
# per-session pointer write; AI continues based on conversation context.
print(colored(
"ℹ Session identity not available; active-task pointer not persisted "
"this session (degraded mode). AI continues based on conversation context.",
Colors.YELLOW,
))
print(colored(
"Hint: run inside an AI IDE/session that exposes session identity, "
"or set TRELLIS_CONTEXT_ID before running task.py start.",
Colors.YELLOW,
))
# Still flip task.json status: planning → in_progress so downstream phases proceed.
if task_json_path.is_file():
data = read_json(task_json_path)
if data and data.get("status") == "planning":
data["status"] = "in_progress"
if write_json(task_json_path, data):
print(colored("✓ Status: planning → in_progress (degraded)", Colors.GREEN))
run_task_hooks("after_start", task_json_path, repo_root)
return 0
active = set_active_task(task_dir, repo_root)
if active:
print(colored(f"✓ Current task set to: {task_dir}", Colors.GREEN))
print(f"Source: {active.source}")
if task_json_path.is_file():
data = read_json(task_json_path)
if data and data.get("status") == "planning":
data["status"] = "in_progress"
if write_json(task_json_path, data):
print(colored("✓ Status: planning → in_progress", Colors.GREEN))
print()
print(colored("The hook will now inject context from this task's jsonl files.", Colors.BLUE))
run_task_hooks("after_start", task_json_path, repo_root)
return 0
else:
print(colored("Error: Failed to set current task", Colors.RED))
return 1
def cmd_finish(args: argparse.Namespace) -> int:
"""Clear active task."""
repo_root = get_repo_root()
active = clear_active_task(repo_root)
current = active.task_path
if not current:
print(colored("No current task set", Colors.YELLOW))
return 0
# Resolve task.json path before clearing
task_json_path = repo_root / current / FILE_TASK_JSON
print(colored(f"✓ Cleared current task (was: {current})", Colors.GREEN))
print(f"Source: {active.source}")
if task_json_path.is_file():
run_task_hooks("after_finish", task_json_path, repo_root)
return 0
def cmd_current(args: argparse.Namespace) -> int:
"""Show active task."""
repo_root = get_repo_root()
active = resolve_active_task(repo_root)
if args.source:
print(f"Current task: {active.task_path or '(none)'}")
print(f"Source: {active.source}")
if active.stale:
print("State: stale")
return 0 if active.task_path else 1
if active.task_path:
print(active.task_path)
return 0
return 1
# =============================================================================
# Command: list
# =============================================================================
def cmd_list(args: argparse.Namespace) -> int:
"""List active tasks."""
repo_root = get_repo_root()
tasks_dir = get_tasks_dir(repo_root)
current_task = get_current_task(repo_root)
developer = get_developer(repo_root)
filter_mine = args.mine
filter_status = args.status
if filter_mine:
if not developer:
print(colored("Error: No developer set. Run init_developer.py first", Colors.RED), file=sys.stderr)
return 1
print(colored(f"My tasks (assignee: {developer}):", Colors.BLUE))
else:
print(colored("All active tasks:", Colors.BLUE))
print()
# Single pass: collect all tasks via shared iterator
all_tasks = {t.dir_name: t for t in iter_active_tasks(tasks_dir)}
all_statuses = {name: t.status for name, t in all_tasks.items()}
# Display tasks hierarchically
count = 0
def _print_task(dir_name: str, indent: int = 0) -> None:
nonlocal count
t = all_tasks[dir_name]
# Apply --mine filter
if filter_mine and (t.assignee or "-") != developer:
return
# Apply --status filter
if filter_status and t.status != filter_status:
return
relative_path = f"{DIR_WORKFLOW}/{DIR_TASKS}/{dir_name}"
marker = ""
if relative_path == current_task:
marker = f" {colored('<- current', Colors.GREEN)}"
# Children progress
progress = children_progress(t.children, all_statuses)
# Package tag
pkg_tag = f" @{t.package}" if t.package else ""
prefix = " " * indent + " - "
if filter_mine:
print(f"{prefix}{dir_name}/ ({t.status}){pkg_tag}{progress}{marker}")
else:
print(f"{prefix}{dir_name}/ ({t.status}){pkg_tag}{progress} [{colored(t.assignee or '-', Colors.CYAN)}]{marker}")
count += 1
# Print children indented
for child_name in t.children:
if child_name in all_tasks:
_print_task(child_name, indent + 1)
# Display only top-level tasks (those without a parent)
for dir_name in sorted(all_tasks.keys()):
if not all_tasks[dir_name].parent:
_print_task(dir_name)
if count == 0:
if filter_mine:
print(" (no tasks assigned to you)")
else:
print(" (no active tasks)")
print()
print(f"Total: {count} task(s)")
return 0
# =============================================================================
# Command: list-archive
# =============================================================================
def cmd_list_archive(args: argparse.Namespace) -> int:
"""List archived tasks."""
repo_root = get_repo_root()
tasks_dir = get_tasks_dir(repo_root)
archive_dir = tasks_dir / "archive"
month = args.month
print(colored("Archived tasks:", Colors.BLUE))
print()
if month:
month_dir = archive_dir / month
if month_dir.is_dir():
print(f"[{month}]")
for d in sorted(month_dir.iterdir()):
if d.is_dir():
print(f" - {d.name}/")
else:
print(f" No archives for {month}")
else:
if archive_dir.is_dir():
for month_dir in sorted(archive_dir.iterdir()):
if month_dir.is_dir():
month_name = month_dir.name
count = sum(1 for d in month_dir.iterdir() if d.is_dir())
print(f"[{month_name}] - {count} task(s)")
return 0
# =============================================================================
# Help
# =============================================================================
def show_usage() -> None:
"""Show usage help."""
print("""Task Management Script
Usage:
python3 task.py create <title> Create new task directory
python3 task.py create <title> --package <pkg> Create task for a specific package
python3 task.py create <title> --parent <dir> Create task as child of parent
python3 task.py add-context <dir> <jsonl> <path> [reason] Add entry to jsonl
python3 task.py validate <dir> Validate jsonl files
python3 task.py list-context <dir> List jsonl entries
python3 task.py start <dir> Set active task
python3 task.py current [--source] Show active task
python3 task.py finish Clear active task
python3 task.py set-branch <dir> <branch> Set git branch
python3 task.py set-base-branch <dir> <branch> Set PR target branch
python3 task.py set-scope <dir> <scope> Set scope for PR title
python3 task.py archive <task-dir> Archive completed task
python3 task.py add-subtask <parent> <child> Link child task to parent
python3 task.py remove-subtask <parent> <child> Unlink child from parent
python3 task.py list [--mine] [--status <status>] List tasks
python3 task.py list-archive [YYYY-MM] List archived tasks
Monorepo options:
--package <pkg> Package name (validated against config.yaml packages)
List options:
--mine, -m Show only tasks assigned to current developer
--status, -s <s> Filter by status (planning, in_progress, review, completed)
Examples:
python3 task.py create "Add login feature" --slug add-login
python3 task.py create "Add login feature" --slug add-login --package cli
python3 task.py create "Child task" --slug child --parent .trellis/tasks/01-21-parent
python3 task.py add-context <dir> implement .trellis/spec/cli/backend/auth.md "Auth guidelines"
python3 task.py set-branch <dir> task/add-login
python3 task.py start .trellis/tasks/01-21-add-login
python3 task.py current --source
python3 task.py finish
python3 task.py archive add-login
python3 task.py add-subtask parent-task child-task # Link existing tasks
python3 task.py remove-subtask parent-task child-task
python3 task.py list # List all active tasks
python3 task.py list --mine # List my tasks only
python3 task.py list --mine --status in_progress # List my in-progress tasks
""")
# =============================================================================
# Main Entry
# =============================================================================
def main() -> int:
"""CLI entry point."""
# Deprecation guard: `init-context` was removed in v0.5.0-beta.12.
# Detect early so argparse doesn't mask the real reason with a generic
# "invalid choice" error.
if len(sys.argv) >= 2 and sys.argv[1] == "init-context":
print(
colored(
"Error: `task.py init-context` was removed in v0.5.0-beta.12.",
Colors.RED,
),
file=sys.stderr,
)
print(
"implement.jsonl / check.jsonl are now seeded on `task.py create` for",
file=sys.stderr,
)
print(
"sub-agent-capable platforms and curated by the AI during planning when needed.",
file=sys.stderr,
)
print("See .trellis/workflow.md planning artifact guidance or run:", file=sys.stderr)
print(
" python3 ./.trellis/scripts/get_context.py --mode phase --step 1",
file=sys.stderr,
)
print(
"Use `task.py add-context <dir> implement|check <path> <reason>` to append entries.",
file=sys.stderr,
)
return 2
parser = argparse.ArgumentParser(
description="Task Management Script",
formatter_class=argparse.RawDescriptionHelpFormatter,
)
subparsers = parser.add_subparsers(dest="command", help="Commands")
# create
p_create = subparsers.add_parser("create", help="Create new task")
p_create.add_argument("title", help="Task title")
p_create.add_argument("--slug", "-s", help="Task slug")
p_create.add_argument("--assignee", "-a", help="Assignee developer")
p_create.add_argument("--priority", "-p", default="P2", help="Priority (P0-P3)")
p_create.add_argument("--description", "-d", help="Task description")
p_create.add_argument("--parent", help="Parent task directory (establishes subtask link)")
p_create.add_argument("--package", help="Package name for monorepo projects")
# add-context
p_add = subparsers.add_parser("add-context", help="Add context entry")
p_add.add_argument("dir", help="Task directory")
p_add.add_argument("file", help="JSONL file (implement|check)")
p_add.add_argument("path", help="File path to add")
p_add.add_argument("reason", nargs="?", help="Reason for adding")
# validate
p_validate = subparsers.add_parser("validate", help="Validate context files")
p_validate.add_argument("dir", help="Task directory")
# list-context
p_listctx = subparsers.add_parser("list-context", help="List context entries")
p_listctx.add_argument("dir", help="Task directory")
# start
p_start = subparsers.add_parser("start", help="Set active task")
p_start.add_argument("dir", help="Task directory")
# current
p_current = subparsers.add_parser("current", help="Show active task")
p_current.add_argument("--source", action="store_true",
help="Show active task source")
# finish
subparsers.add_parser("finish", help="Clear active task")
# set-branch
p_branch = subparsers.add_parser("set-branch", help="Set git branch")
p_branch.add_argument("dir", help="Task directory")
p_branch.add_argument("branch", help="Branch name")
# set-base-branch
p_base = subparsers.add_parser("set-base-branch", help="Set PR target branch")
p_base.add_argument("dir", help="Task directory")
p_base.add_argument("base_branch", help="Base branch name (PR target)")
# set-scope
p_scope = subparsers.add_parser("set-scope", help="Set scope")
p_scope.add_argument("dir", help="Task directory")
p_scope.add_argument("scope", help="Scope name")
# archive
p_archive = subparsers.add_parser("archive", help="Archive task")
p_archive.add_argument("name", help="Task directory or name")
p_archive.add_argument("--no-commit", action="store_true", help="Skip auto git commit after archive")
# list
p_list = subparsers.add_parser("list", help="List tasks")
p_list.add_argument("--mine", "-m", action="store_true", help="My tasks only")
p_list.add_argument("--status", "-s", help="Filter by status")
# add-subtask
p_addsub = subparsers.add_parser("add-subtask", help="Link child task to parent")
p_addsub.add_argument("parent_dir", help="Parent task directory")
p_addsub.add_argument("child_dir", help="Child task directory")
# remove-subtask
p_rmsub = subparsers.add_parser("remove-subtask", help="Unlink child task from parent")
p_rmsub.add_argument("parent_dir", help="Parent task directory")
p_rmsub.add_argument("child_dir", help="Child task directory")
# list-archive
p_listarch = subparsers.add_parser("list-archive", help="List archived tasks")
p_listarch.add_argument("month", nargs="?", help="Month (YYYY-MM)")
args = parser.parse_args()
if not args.command:
show_usage()
return 1
commands = {
"create": cmd_create,
"add-context": cmd_add_context,
"validate": cmd_validate,
"list-context": cmd_list_context,
"start": cmd_start,
"current": cmd_current,
"finish": cmd_finish,
"set-branch": cmd_set_branch,
"set-base-branch": cmd_set_base_branch,
"set-scope": cmd_set_scope,
"archive": cmd_archive,
"add-subtask": cmd_add_subtask,
"remove-subtask": cmd_remove_subtask,
"list": cmd_list,
"list-archive": cmd_list_archive,
}
if args.command in commands:
return commands[args.command](args)
else:
show_usage()
return 1
if __name__ == "__main__":
sys.exit(main())
.trellis/spec/guides/code-reuse-thinking-guide.md
+223
View File
@@ -0,0 +1,223 @@
# Code Reuse Thinking Guide
> **Purpose**: Stop and think before creating new code - does it already exist?
---
## The Problem
**Duplicated code is the #1 source of inconsistency bugs.**
When you copy-paste or rewrite existing logic:
- Bug fixes don't propagate
- Behavior diverges over time
- Codebase becomes harder to understand
---
## Before Writing New Code
### Step 1: Search First
```bash
# Search for similar function names
grep -r "functionName" .
# Search for similar logic
grep -r "keyword" .
```
### Step 2: Ask These Questions
| Question | If Yes... |
|----------|-----------|
| Does a similar function exist? | Use or extend it |
| Is this pattern used elsewhere? | Follow the existing pattern |
| Could this be a shared utility? | Create it in the right place |
| Am I copying code from another file? | **STOP** - extract to shared |
---
## Common Duplication Patterns
### Pattern 1: Copy-Paste Functions
**Bad**: Copying a validation function to another file
**Good**: Extract to shared utilities, import where needed
### Pattern 2: Similar Components
**Bad**: Creating a new component that's 80% similar to existing
**Good**: Extend existing component with props/variants
### Pattern 3: Repeated Constants
**Bad**: Defining the same constant in multiple files
**Good**: Single source of truth, import everywhere
### Pattern 4: Repeated Payload Field Extraction
**Bad**: Multiple consumers cast the same JSON/event fields locally:
```typescript
const description = (ev as { description?: string }).description;
const context = (ev as { context?: ContextEntry[] }).context;
```
This is duplicated contract logic even when the code is only two lines. Each
consumer now has its own definition of what a valid payload means.
**Good**: Put the decoder, type guard, or projection next to the data owner:
```typescript
if (isThreadEvent(ev)) {
renderThreadEvent(ev);
}
```
**Rule**: If the same untyped payload field is read in 2+ places, create a
shared type guard / normalizer / projection before adding a third reader.
---
## When to Abstract
**Abstract when**:
- Same code appears 3+ times
- Logic is complex enough to have bugs
- Multiple people might need this
**Don't abstract when**:
- Only used once
- Trivial one-liner
- Abstraction would be more complex than duplication
---
## After Batch Modifications
When you've made similar changes to multiple files:
1. **Review**: Did you catch all instances?
2. **Search**: Run grep to find any missed
3. **Consider**: Should this be abstracted?
### Reducers Should Use Exhaustive Structure
When state is derived from action-like values (`action`, `kind`, `status`,
`phase`), prefer a reducer with one `switch` over scattered `if/else` updates.
```typescript
// BAD - action-specific state transitions are hard to audit
if (action === "opened") { ... }
else if (action === "comment") { ... }
else if (action === "status") { ... }
// GOOD - one reducer owns the transition table
switch (event.action) {
case "opened":
...
return;
case "comment":
...
return;
}
```
This matters when the event log is the source of truth. A reducer is the
documented replay model; display code and commands should not duplicate pieces
of that replay model.
---
## Checklist Before Commit
- [ ] Searched for existing similar code
- [ ] No copy-pasted logic that should be shared
- [ ] No repeated untyped payload field extraction outside a shared decoder
- [ ] Constants defined in one place
- [ ] Similar patterns follow same structure
- [ ] Reducer/action transitions live in one reducer or command dispatcher
---
## Gotcha: Python if/elif/else Exhaustive Check
**Problem**: Python's if/elif/else chains have no compile-time exhaustive check. When you add a new value to a `Literal` type (e.g., `Platform`), existing if/elif/else chains silently fall through to `else` with wrong defaults.
**Symptom**: New platform works partially — some methods return Claude defaults instead of platform-specific values. No error is raised.
**Example** (`cli_adapter.py`):
```python
# BAD: "gemini" falls through to else, returns "claude"
@property
def cli_name(self) -> str:
if self.platform == "opencode":
return "opencode"
else:
return "claude" # gemini silently gets "claude"!
# GOOD: explicit branch for every platform
@property
def cli_name(self) -> str:
if self.platform == "opencode":
return "opencode"
elif self.platform == "gemini":
return "gemini"
else:
return "claude"
```
**Prevention**: When adding a new value to a Python `Literal` type, search for ALL if/elif/else chains that switch on that type and add explicit branches. Don't rely on `else` being correct for new values.
---
## Gotcha: Asymmetric Mechanisms Producing Same Output
**Problem**: When two different mechanisms must produce the same file set (e.g., recursive directory copy for init vs. manual `files.set()` for update), structural changes (renaming, moving, adding subdirectories) only propagate through the automatic mechanism. The manual one silently drifts.
**Symptom**: Init works perfectly, but update creates files at wrong paths or misses files entirely.
**Prevention**:
- **Best**: Eliminate the asymmetry — have the manual path call the automatic one (e.g., `collectTemplateFiles()` calls `getAllScripts()` instead of maintaining its own list)
- **If asymmetry is unavoidable**: Add a regression test that compares outputs from both mechanisms
- When migrating directory structures, search for ALL code paths that reference the old structure
**Real example**: `trellis update` had a manual `files.set()` list for 11 scripts that `getAllScripts()` already tracked. Fix: replaced the manual list with a `for..of getAllScripts()` loop. See `update.ts` refactor in v0.4.0-beta.3.
---
## Template File Registration (Trellis-specific)
When adding new files to `src/templates/trellis/scripts/`:
**Single registration point**: `src/templates/trellis/index.ts`
1. Add `export const xxxScript = readTemplate("scripts/path/file.py");`
2. Add to `getAllScripts()` Map
That's it. `commands/update.ts` uses `getAllScripts()` directly — no manual sync needed.
**Why this matters**: Without registration in `getAllScripts()`, `trellis update` won't sync the file to user projects. Bug fixes and features won't propagate.
**History**: Before v0.4.0-beta.3, `update.ts` had its own hand-maintained file list that frequently fell out of sync with `getAllScripts()`. This caused 11 Python files to be silently skipped during `trellis update`. The fix was to eliminate the duplicate list and use `getAllScripts()` as the single source of truth.
### Quick Checklist for New Scripts
```bash
# After adding a new .py file, verify it's in getAllScripts():
grep -l "newFileName" src/templates/trellis/index.ts # Should match
```
### Template Sync Convention
`.trellis/scripts/` (dogfooded) and `packages/cli/src/templates/trellis/scripts/` (template) must stay identical. After editing `.trellis/scripts/`, always sync:
```bash
rsync -av --delete --exclude='__pycache__' .trellis/scripts/ packages/cli/src/templates/trellis/scripts/
```
**Gotcha**: Running rsync with wrong source/destination paths can create nested garbage directories (e.g., `.trellis/scripts/packages/cli/...`). Always double-check paths before running.
.trellis/spec/guides/cross-layer-thinking-guide.md
+327
View File
@@ -0,0 +1,327 @@
# Cross-Layer Thinking Guide
> **Purpose**: Think through data flow across layers before implementing.
---
## The Problem
**Most bugs happen at layer boundaries**, not within layers.
Common cross-layer bugs:
- API returns format A, frontend expects format B
- Database stores X, service transforms to Y, but loses data
- Multiple layers implement the same logic differently
---
## Before Implementing Cross-Layer Features
### Step 1: Map the Data Flow
Draw out how data moves:
```
Source → Transform → Store → Retrieve → Transform → Display
```
For each arrow, ask:
- What format is the data in?
- What could go wrong?
- Who is responsible for validation?
### Step 2: Identify Boundaries
| Boundary | Common Issues |
| --------------------- | --------------------------------- |
| API ↔ Service | Type mismatches, missing fields |
| Service ↔ Database | Format conversions, null handling |
| Backend ↔ Frontend | Serialization, date formats |
| Component ↔ Component | Props shape changes |
### Step 3: Define Contracts
For each boundary:
- What is the exact input format?
- What is the exact output format?
- What errors can occur?
---
## Common Cross-Layer Mistakes
### Mistake 1: Implicit Format Assumptions
**Bad**: Assuming date format without checking
**Good**: Explicit format conversion at boundaries
### Mistake 2: Scattered Validation
**Bad**: Validating the same thing in multiple layers
**Good**: Validate once at the entry point
### Mistake 3: Leaky Abstractions
**Bad**: Component knows about database schema
**Good**: Each layer only knows its neighbors
### Mistake 4: Every Consumer Parses The Same Payload
**Bad**: A command reads JSONL events and casts fields inline:
```typescript
const thread = (ev as { thread?: string }).thread;
const labels = (ev as { labels?: string[] }).labels;
```
This looks local, but it means every consumer owns a private version of the
event contract. The next field change will update one command and miss another.
**Good**: Decode once at the event boundary, then export typed projections:
```typescript
if (!isThreadEvent(ev)) return false;
return ev.thread === filter.thread;
```
**Rule**: For append-only logs, JSON streams, RPC payloads, or config files,
create one owner for:
- event / payload type definitions
- type guards and normalization from `unknown`
- metadata projections used by UI commands
- reducers that replay state from the source of truth
Rendering code may format fields, but it must not redefine the payload contract.
---
## Checklist for Cross-Layer Features
Before implementation:
- [ ] Mapped the complete data flow
- [ ] Identified all layer boundaries
- [ ] Defined format at each boundary
- [ ] Decided where validation happens
After implementation:
- [ ] Tested with edge cases (null, empty, invalid)
- [ ] Verified error handling at each boundary
- [ ] Checked data survives round-trip
- [ ] Checked that consumers import shared decoders / projections instead of
casting payload fields locally
- [ ] Checked that derived state points back to the source event identifier
(`seq`, `id`, `version`) instead of inventing a second cursor
---
## Cross-Platform Template Consistency
In Trellis, command templates (e.g., `record-session.md`) exist in **multiple platforms** with identical or near-identical content. This is a cross-layer boundary.
### Checklist: After Modifying Any Command Template
- [ ] Find all platforms with the same command: `find src/templates/*/commands/trellis/ -name "<command>.*"`
- [ ] Update all platform copies (Markdown `.md` and TOML `.toml`)
- [ ] For Gemini TOML: adapt line continuations (`\\` vs `\`) and triple-quoted strings
- [ ] Run `/trellis:check-cross-layer` to verify nothing was missed
**Real-world example**: Updated `record-session.md` in Claude to use `--mode record`, but forgot iFlow, Kilo, OpenCode, and Gemini — caught by cross-layer check.
---
## Generated Runtime Template Upgrade Consistency
Some generated files are both documentation and runtime input. In Trellis,
`.trellis/workflow.md` is parsed by `get_context.py`, `workflow_phase.py`,
SessionStart filters, and per-turn hooks. Template changes must be validated
against both fresh init and upgrade paths.
### Checklist: After Modifying A Runtime-Parsed Template
- [ ] Identify every runtime parser that reads the template, not just the file
writer that installs it
- [ ] Check whether relevant syntax lives outside obvious managed regions
such as tag blocks
- [ ] Verify fresh `init` output and a versioned `update` scenario that writes
the older `.trellis/.version`
- [ ] Add an upgrade regression using an older pristine template fixture, then
assert the installed file reaches the current packaged shape
- [ ] Update the backend spec that owns the runtime contract
---
## Versioned Documentation Boundary
Versioned documentation is a cross-layer boundary: source paths, `docs.json`
version routing, and the rendered version selector must all describe the same
release line.
### Checklist: Before Editing Versioned Docs
- [ ] Identify the target release line: stable, beta, or RC
- [ ] Verify the edited MDX path matches that line:
- stable: `docs-site/{start,advanced,...}` and `docs-site/zh/{start,advanced,...}`
- beta: `docs-site/beta/**` and `docs-site/zh/beta/**`
- RC: `docs-site/rc/**` and `docs-site/zh/rc/**`
- [ ] Verify `docs.json` navigation points the version label to the same paths
- [ ] Grep the opposite tree for release-line-specific terms before committing
- [ ] Treat beta content appearing under root release paths as a source-path bug,
not a rendering bug
**Real-world example**: A beta-only task workflow change documented
`prd.md` + `design.md` + `implement.md`, task-creation consent, and Codex
mode banners under root `start/` and `advanced/` paths. The docs site then
served 0.6 beta behavior under the Release selector. The fix was to restore root
release docs, move the 0.6 content to `beta/` and `zh/beta/`, and add a grep
audit for beta markers against the root release tree.
**Real-world example**: Codex inline mode changed workflow platform markers from
`[Codex]` / `[Kilo, Antigravity, Windsurf]` to `[codex-sub-agent]` /
`[codex-inline, Kilo, Antigravity, Windsurf]`. Fresh init was correct, but
`trellis update` only merged `[workflow-state:*]` blocks and preserved stale
markers outside those blocks. Result: upgraded projects got new hook scripts
but old workflow routing, so `get_context.py --mode phase --platform codex`
could return empty Phase 2.1 detail.
---
## Mode-Detection Probe Checklist
When a CLI auto-detects a mode by probing a remote resource (e.g., checking if `index.json` exists to decide marketplace vs direct download):
### Before implementing:
- [ ] Probe runs in **ALL** code paths that use the result (interactive, `-y`, `--flag` combos)
- [ ] 404 vs transient error are distinguished — don't treat both as "not found"
- [ ] Transient errors **abort or retry**, never silently switch modes
- [ ] Shared state (caches, prefetched data) is **reset** when context changes (e.g., user switches source)
- [ ] **Shortcut paths** (e.g., `--template` skipping picker) must have the same error-handling quality as the probed path — check that downstream functions don't call catch-all wrappers
### After implementing:
- [ ] Trace every path from probe result to the mode-decision branch — no fallthrough
- [ ] External format contracts (giget URI, raw URLs) are tested or at least documented as comments
- [ ] Metadata reads consume a complete response or use a streaming parser — never parse a fixed-size prefix as full JSON
- [ ] When reconstructing a composite identifier from parsed parts, verify **all** fields are included and in the **correct position** (e.g., `provider:repo/path#ref` not `provider:repo#ref/path`)
- [ ] Verify that **action functions** called after a shortcut don't internally use the old catch-all fetch — they must use the probe-quality variant when error distinction matters
**Real-world example**: Custom registry flow had 8 bugs across 3 review rounds: (1) probe only ran in interactive mode, (2) transient errors fell through to wrong mode, (3) giget URI had `#ref` in wrong position, (4) prefetched templates leaked across source switches, (5) `--template` shortcut bypassed probe but `downloadTemplateById` internally used catch-all `fetchTemplateIndex`, turning timeouts into "Template not found".
**Real-world example**: Agent-session update hints fetched npm `latest` metadata with `response.read(4096)` and then parsed it as complete JSON. The `@mindfoldhq/trellis` package metadata exceeded 4 KB, so the JSON was truncated, parse failed silently, and the first session injection showed no update hint. Fix: read the complete response before parsing, and add a regression where `version` is followed by an 8 KB metadata tail.
---
## Cross-Platform Template Consistency
In Trellis, command templates (e.g., `record-session.md`) exist in **multiple platforms** with identical or near-identical content. This is a cross-layer boundary.
### Checklist: After Modifying Any Command Template
- [ ] Find all platforms with the same command: `find src/templates/*/commands/trellis/ -name "<command>.*"`
- [ ] Update all platform copies (Markdown `.md` and TOML `.toml`)
- [ ] For Gemini TOML: adapt line continuations (`\\` vs `\`) and triple-quoted strings
- [ ] Run `/trellis:check-cross-layer` to verify nothing was missed
**Real-world example**: Updated `record-session.md` in Claude to use `--mode record`, but forgot iFlow, Kilo, OpenCode, and Gemini — caught by cross-layer check.
---
## Generated Runtime Template Upgrade Consistency
Some generated files are both documentation and runtime input. In Trellis,
`.trellis/workflow.md` is parsed by `get_context.py`, `workflow_phase.py`,
SessionStart filters, and per-turn hooks. Template changes must be validated
against both fresh init and upgrade paths.
### Checklist: After Modifying A Runtime-Parsed Template
- [ ] Identify every runtime parser that reads the template, not just the file
writer that installs it
- [ ] Check whether relevant syntax lives outside obvious managed regions
such as tag blocks
- [ ] Verify fresh `init` output and a versioned `update` scenario that writes
the older `.trellis/.version`
- [ ] Add an upgrade regression using an older pristine template fixture, then
assert the installed file reaches the current packaged shape
- [ ] Update the backend spec that owns the runtime contract
**Real-world example**: Codex inline mode changed workflow platform markers from
`[Codex]` / `[Kilo, Antigravity, Windsurf]` to `[codex-sub-agent]` /
`[codex-inline, Kilo, Antigravity, Windsurf]`. Fresh init was correct, but
`trellis update` only merged `[workflow-state:*]` blocks and preserved stale
markers outside those blocks. Result: upgraded projects got new hook scripts
but old workflow routing, so `get_context.py --mode phase --platform codex`
could return empty Phase 2.1 detail.
---
## Mode-Detection Probe Checklist
When a CLI auto-detects a mode by probing a remote resource (e.g., checking if `index.json` exists to decide marketplace vs direct download):
### Before implementing:
- [ ] Probe runs in **ALL** code paths that use the result (interactive, `-y`, `--flag` combos)
- [ ] 404 vs transient error are distinguished — don't treat both as "not found"
- [ ] Transient errors **abort or retry**, never silently switch modes
- [ ] Shared state (caches, prefetched data) is **reset** when context changes (e.g., user switches source)
- [ ] **Shortcut paths** (e.g., `--template` skipping picker) must have the same error-handling quality as the probed path — check that downstream functions don't call catch-all wrappers
### After implementing:
- [ ] Trace every path from probe result to the mode-decision branch — no fallthrough
- [ ] External format contracts (giget URI, raw URLs) are tested or at least documented as comments
- [ ] Metadata reads consume a complete response or use a streaming parser — never parse a fixed-size prefix as full JSON
- [ ] When reconstructing a composite identifier from parsed parts, verify **all** fields are included and in the **correct position** (e.g., `provider:repo/path#ref` not `provider:repo#ref/path`)
- [ ] Verify that **action functions** called after a shortcut don't internally use the old catch-all fetch — they must use the probe-quality variant when error distinction matters
**Real-world example**: Custom registry flow had 8 bugs across 3 review rounds: (1) probe only ran in interactive mode, (2) transient errors fell through to wrong mode, (3) giget URI had `#ref` in wrong position, (4) prefetched templates leaked across source switches, (5) `--template` shortcut bypassed probe but `downloadTemplateById` internally used catch-all `fetchTemplateIndex`, turning timeouts into "Template not found".
**Real-world example**: Agent-session update hints fetched npm `latest` metadata with `response.read(4096)` and then parsed it as complete JSON. The `@mindfoldhq/trellis` package metadata exceeded 4 KB, so the JSON was truncated, parse failed silently, and the first session injection showed no update hint. Fix: read the complete response before parsing, and add a regression where `version` is followed by an 8 KB metadata tail.
---
## When to Create Flow Documentation
Create detailed flow docs when:
- Feature spans 3+ layers
- Multiple teams are involved
- Data format is complex
- Feature has caused bugs before
---
## Event Log / Projection Boundary
Append-only logs are cross-layer contracts. A single event travels through:
```
CLI input → event writer → events.jsonl → reader → filter → reducer → display
```
### Checklist: After Adding A New Event Kind Or Field
- [ ] Add the event kind to the central event taxonomy
- [ ] Add a typed event variant or type guard at the event layer
- [ ] Add normalization helpers for array/object fields that come from
user input or JSON
- [ ] Keep `seq` / `id` assignment in the event writer only
- [ ] Make filters and reducers consume the typed event guard, not local casts
- [ ] Make display code consume reducer output or typed events, not raw JSON
- [ ] Add at least one regression that proves history replay and live filtering
use the same filter model
**Real-world example**: Thread channels added `kind: "thread"`, `description`,
`context`, labels, and `lastSeq`. The first implementation replayed thread
state correctly, but several commands still re-parsed event payload fields with
local casts. The fix was to make the core event layer own `ThreadChannelEvent`
and `isThreadEvent`, make `reduceChannelMetadata` the only channel metadata
projection, and make `reduceThreads` the only thread replay reducer.
.trellis/spec/guides/index.md
+97
View File
@@ -0,0 +1,97 @@
# Thinking Guides
> **Purpose**: Expand your thinking to catch things you might not have considered.
---
## Why Thinking Guides?
**Most bugs and tech debt come from "didn't think of that"**, not from lack of skill:
- Didn't think about what happens at layer boundaries → cross-layer bugs
- Didn't think about code patterns repeating → duplicated code everywhere
- Didn't think about edge cases → runtime errors
- Didn't think about future maintainers → unreadable code
These guides help you **ask the right questions before coding**.
---
## Available Guides
| Guide | Purpose | When to Use |
|-------|---------|-------------|
| [Code Reuse Thinking Guide](./code-reuse-thinking-guide.md) | Identify patterns and reduce duplication | When you notice repeated patterns |
| [Cross-Layer Thinking Guide](./cross-layer-thinking-guide.md) | Think through data flow across layers | Features spanning multiple layers |
---
## Quick Reference: Thinking Triggers
### When to Think About Cross-Layer Issues
- [ ] Feature touches 3+ layers (API, Service, Component, Database)
- [ ] Data format changes between layers
- [ ] Multiple consumers need the same data
- [ ] You're not sure where to put some logic
- [ ] You are adding an event kind, JSONL record, RPC payload, or config field
- [ ] UI / command code starts casting raw payload fields directly
→ Read [Cross-Layer Thinking Guide](./cross-layer-thinking-guide.md)
### When to Think About Code Reuse
- [ ] You're writing similar code to something that exists
- [ ] You see the same pattern repeated 3+ times
- [ ] You're adding a new field to multiple places
- [ ] **You're modifying any constant or config**
- [ ] **You're creating a new utility/helper function** ← Search first!
- [ ] Two files read the same untyped payload field with local casts
- [ ] Multiple branches update the same derived state from `kind` / `action`
→ Read [Code Reuse Thinking Guide](./code-reuse-thinking-guide.md)
### When Verifying AI Cross-Review Results
- [ ] Reviewer claims "user input can be malicious" → Check the actual data source (internal manifest? user config? external API?)
- [ ] Reviewer flags "missing validation" → Is the data from a trusted internal source?
- [ ] Reviewer says "behavior change" → Read the code comments — is it intentional design?
- [ ] Reviewer identifies a "bug" in test → Mentally delete the feature being tested — does the test still pass? If yes → tautological test
**Common AI reviewer false-positive patterns**:
1. **Trust boundary confusion**: Treating internal data (bundled JSON manifests) as untrusted external input
2. **Ignoring design comments**: Flagging intentional behavior documented in code comments as bugs
3. **Variable misreading**: Not tracing a variable to its actual definition (e.g., Map keyed by path vs name)
**Verification rule**: Every CRITICAL/WARNING finding must be verified against the actual code before prioritizing. Budget ~35% false-positive rate for AI reviews.
---
## Pre-Modification Rule (CRITICAL)
> **Before changing ANY value, ALWAYS search first!**
```bash
# Search for the value you're about to change
grep -r "value_to_change" .
```
This single habit prevents most "forgot to update X" bugs.
---
## How to Use This Directory
1. **Before coding**: Skim the relevant thinking guide
2. **During coding**: If something feels repetitive or complex, check the guides
3. **After bugs**: Add new insights to the relevant guide (learn from mistakes)
---
## Contributing
Found a new "didn't think of that" moment? Add it to the relevant guide.
---
**Core Principle**: 30 minutes of thinking saves 3 hours of debugging.
.trellis/spec/vendor/ComfyUI_frontend/frontend/component-guidelines.md
Vendored
+59
View File
@@ -0,0 +1,59 @@
# Component Guidelines
> How components are built in this project.
---
## Overview
<!--
Document your project's component conventions here.
Questions to answer:
- What component patterns do you use?
- How are props defined?
- How do you handle composition?
- What accessibility standards apply?
-->
(To be filled by the team)
---
## Component Structure
<!-- Standard structure of a component file -->
(To be filled by the team)
---
## Props Conventions
<!-- How props should be defined and typed -->
(To be filled by the team)
---
## Styling Patterns
<!-- How styles are applied (CSS modules, styled-components, Tailwind, etc.) -->
(To be filled by the team)
---
## Accessibility
<!-- A11y requirements and patterns -->
(To be filled by the team)
---
## Common Mistakes
<!-- Component-related mistakes your team has made -->
(To be filled by the team)
.trellis/spec/vendor/ComfyUI_frontend/frontend/directory-structure.md
Vendored
+54
View File
@@ -0,0 +1,54 @@
# Directory Structure
> How frontend code is organized in this project.
---
## Overview
<!--
Document your project's frontend directory structure here.
Questions to answer:
- Where do components live?
- How are features/modules organized?
- Where are shared utilities?
- How are assets organized?
-->
(To be filled by the team)
---
## Directory Layout
```
<!-- Replace with your actual structure -->
src/
├── ...
└── ...
```
---
## Module Organization
<!-- How should new features be organized? -->
(To be filled by the team)
---
## Naming Conventions
<!-- File and folder naming rules -->
(To be filled by the team)
---
## Examples
<!-- Link to well-organized modules as examples -->
(To be filled by the team)
.trellis/spec/vendor/ComfyUI_frontend/frontend/hook-guidelines.md
Vendored
+51
View File
@@ -0,0 +1,51 @@
# Hook Guidelines
> How hooks are used in this project.
---
## Overview
<!--
Document your project's hook conventions here.
Questions to answer:
- What custom hooks do you have?
- How do you handle data fetching?
- What are the naming conventions?
- How do you share stateful logic?
-->
(To be filled by the team)
---
## Custom Hook Patterns
<!-- How to create and structure custom hooks -->
(To be filled by the team)
---
## Data Fetching
<!-- How data fetching is handled (React Query, SWR, etc.) -->
(To be filled by the team)
---
## Naming Conventions
<!-- Hook naming rules (use*, etc.) -->
(To be filled by the team)
---
## Common Mistakes
<!-- Hook-related mistakes your team has made -->
(To be filled by the team)
.trellis/spec/vendor/ComfyUI_frontend/frontend/index.md
Vendored
+39
View File
@@ -0,0 +1,39 @@
# Frontend Development Guidelines
> Best practices for frontend development in this project.
---
## Overview
This directory contains guidelines for frontend development. Fill in each file with your project's specific conventions.
---
## Guidelines Index
| Guide | Description | Status |
|-------|-------------|--------|
| [Directory Structure](./directory-structure.md) | Module organization and file layout | To fill |
| [Component Guidelines](./component-guidelines.md) | Component patterns, props, composition | To fill |
| [Hook Guidelines](./hook-guidelines.md) | Custom hooks, data fetching patterns | To fill |
| [State Management](./state-management.md) | Local state, global state, server state | To fill |
| [Quality Guidelines](./quality-guidelines.md) | Code standards, forbidden patterns | To fill |
| [Type Safety](./type-safety.md) | Type patterns, validation | To fill |
---
## How to Fill These Guidelines
For each guideline file:
1. Document your project's **actual conventions** (not ideals)
2. Include **code examples** from your codebase
3. List **forbidden patterns** and why
4. Add **common mistakes** your team has made
The goal is to help AI assistants and new team members understand how YOUR project works.
---
**Language**: All documentation should be written in **English**.
.trellis/spec/vendor/ComfyUI_frontend/frontend/quality-guidelines.md
Vendored
+51
View File
@@ -0,0 +1,51 @@
# Quality Guidelines
> Code quality standards for frontend development.
---
## Overview
<!--
Document your project's quality standards here.
Questions to answer:
- What patterns are forbidden?
- What linting rules do you enforce?
- What are your testing requirements?
- What code review standards apply?
-->
(To be filled by the team)
---
## Forbidden Patterns
<!-- Patterns that should never be used and why -->
(To be filled by the team)
---
## Required Patterns
<!-- Patterns that must always be used -->
(To be filled by the team)
---
## Testing Requirements
<!-- What level of testing is expected -->
(To be filled by the team)
---
## Code Review Checklist
<!-- What reviewers should check -->
(To be filled by the team)
.trellis/spec/vendor/ComfyUI_frontend/frontend/state-management.md
Vendored
+51
View File
@@ -0,0 +1,51 @@
# State Management
> How state is managed in this project.
---
## Overview
<!--
Document your project's state management conventions here.
Questions to answer:
- What state management solution do you use?
- How is local vs global state decided?
- How do you handle server state?
- What are the patterns for derived state?
-->
(To be filled by the team)
---
## State Categories
<!-- Local state, global state, server state, URL state -->
(To be filled by the team)
---
## When to Use Global State
<!-- Criteria for promoting state to global -->
(To be filled by the team)
---
## Server State
<!-- How server data is cached and synchronized -->
(To be filled by the team)
---
## Common Mistakes
<!-- State management mistakes your team has made -->
(To be filled by the team)
.trellis/spec/vendor/ComfyUI_frontend/frontend/type-safety.md
Vendored
+51
View File
@@ -0,0 +1,51 @@
# Type Safety
> Type safety patterns in this project.
---
## Overview
<!--
Document your project's type safety conventions here.
Questions to answer:
- What type system do you use?
- How are types organized?
- What validation library do you use?
- How do you handle type inference?
-->
(To be filled by the team)
---
## Type Organization
<!-- Where types are defined, shared types vs local types -->
(To be filled by the team)
---
## Validation
<!-- Runtime validation patterns (Zod, Yup, io-ts, etc.) -->
(To be filled by the team)
---
## Common Patterns
<!-- Type utilities, generics, type guards -->
(To be filled by the team)
---
## Forbidden Patterns
<!-- any, type assertions, etc. -->
(To be filled by the team)
.trellis/tasks/00-bootstrap-guidelines/prd.md
+119
View File
@@ -0,0 +1,119 @@
# Bootstrap Task: Fill Project Development Guidelines
**You (the AI) are running this task. The developer does not read this file.**
The developer just ran `trellis init` on this project for the first time.
`.trellis/` now exists with empty spec scaffolding, and this bootstrap task
exists under `.trellis/tasks/`. When they want to work on it, they should start
this task from a session that provides Trellis session identity.
**Your job**: help them populate `.trellis/spec/` with the team's real
coding conventions. Every future AI session — this project's
`trellis-implement` and `trellis-check` sub-agents — auto-loads spec files
listed in per-task jsonl manifests. Empty spec = sub-agents write generic
code. Real spec = sub-agents match the team's actual patterns.
Don't dump instructions. Open with a short greeting, figure out if the repo
has any existing convention docs (CLAUDE.md, .cursorrules, etc.), and drive
the rest conversationally.
---
## Status (update the checkboxes as you complete each item)
- [ ] Fill guidelines for vendor/ComfyUI_frontend
- [ ] Add code examples
---
## Spec files to populate
### Package: vendor/ComfyUI_frontend (`spec/vendor/ComfyUI_frontend/`)
- Frontend guidelines: `.trellis/spec/vendor/ComfyUI_frontend/frontend/`
### Thinking guides (already populated)
`.trellis/spec/guides/` contains general thinking guides pre-filled with
best practices. Customize only if something clearly doesn't fit this project.
---
## How to fill the spec
### Step 1: Import from existing convention files first (preferred)
Search the repo for existing convention docs. If any exist, read them and
extract the relevant rules into the matching `.trellis/spec/` files —
usually much faster than documenting from scratch.
| File / Directory | Tool |
|------|------|
| `CLAUDE.md` / `CLAUDE.local.md` | Claude Code |
| `AGENTS.md` | Codex / Claude Code / agent-compatible tools |
| `.cursorrules` | Cursor |
| `.cursor/rules/*.mdc` | Cursor (rules directory) |
| `.windsurfrules` | Windsurf |
| `.clinerules` | Cline |
| `.roomodes` | Roo Code |
| `.github/copilot-instructions.md` | GitHub Copilot |
| `.vscode/settings.json` → `github.copilot.chat.codeGeneration.instructions` | VS Code Copilot |
| `CONVENTIONS.md` / `.aider.conf.yml` | aider |
| `CONTRIBUTING.md` | General project conventions |
| `.editorconfig` | Editor formatting rules |
### Step 2: Analyze the codebase for anything not covered by existing docs
Scan real code to discover patterns. Before writing each spec file:
- Find 2-3 real examples of each pattern in the codebase.
- Reference real file paths (not hypothetical ones).
- Document anti-patterns the team clearly avoids.
### Step 3: Document reality, not ideals
**Critical**: write what the code *actually does*, not what it should do.
Sub-agents match the spec, so aspirational patterns that don't exist in the
codebase will cause sub-agents to write code that looks out of place.
If the team has known tech debt, document the current state — improvement
is a separate conversation, not a bootstrap concern.
---
## Quick explainer of the runtime (share when they ask "why do we need spec at all")
- Every AI coding task spawns two sub-agents: `trellis-implement` (writes
code) and `trellis-check` (verifies quality).
- Each task has `implement.jsonl` / `check.jsonl` manifests listing which
spec files to load.
- The platform hook auto-injects those spec files + the task's `prd.md`
into every sub-agent prompt, so the sub-agent codes/reviews per team
conventions without anyone pasting them manually.
- Source of truth: `.trellis/spec/`. That's why filling it well now pays
off forever.
---
## Completion
When the developer confirms the checklist items above are done with real
examples (not placeholders), guide them to run:
```bash
python3 ./.trellis/scripts/task.py finish
python3 ./.trellis/scripts/task.py archive 00-bootstrap-guidelines
```
After archive, every new developer who joins this project will get a
`00-join-<slug>` onboarding task instead of this bootstrap task.
---
## Suggested opening line
"Welcome to Trellis! Your init just set me up to help you fill the project
spec — a one-time setup so every future AI session follows the team's
conventions instead of writing generic code. Before we start, do you have
any existing convention docs (CLAUDE.md, .cursorrules, CONTRIBUTING.md,
etc.) I can pull from, or should I scan the codebase from scratch?"
.trellis/tasks/00-bootstrap-guidelines/task.json
+28
View File
@@ -0,0 +1,28 @@
{
"id": "00-bootstrap-guidelines",
"name": "00-bootstrap-guidelines",
"title": "Bootstrap Guidelines",
"description": "Fill in project development guidelines for AI agents",
"status": "in_progress",
"dev_type": "docs",
"scope": null,
"package": null,
"priority": "P1",
"creator": "boos4721",
"assignee": "boos4721",
"createdAt": "2026-06-20",
"completedAt": null,
"branch": null,
"base_branch": null,
"worktree_path": null,
"commit": null,
"pr_url": null,
"subtasks": [],
"children": [],
"parent": null,
"relatedFiles": [
".trellis/spec/vendor/ComfyUI_frontend/"
],
"notes": "First-time setup task created by trellis init (fullstack project)",
"meta": {}
}
.trellis/workflow.md
+706
View File
@@ -0,0 +1,706 @@
# Development Workflow
---
## Core Principles
1. **Plan before code** — figure out what to do before you start
2. **Specs injected, not remembered** — guidelines are injected via hook/skill, not recalled from memory
3. **Persist everything** — research, decisions, and lessons all go to files; conversations get compacted, files don't
4. **Incremental development** — one task at a time
5. **Capture learnings** — after each task, review and write new knowledge back to spec
---
## Trellis System
### Developer Identity
On first use, initialize your identity:
```bash
python3 ./.trellis/scripts/init_developer.py <your-name>
```
Creates `.trellis/.developer` (gitignored) + `.trellis/workspace/<your-name>/`.
### Spec System
`.trellis/spec/` holds coding guidelines organized by package and layer.
- `.trellis/spec/<package>/<layer>/index.md` — entry point with **Pre-Development Checklist** + **Quality Check**. Actual guidelines live in the `.md` files it points to.
- `.trellis/spec/guides/index.md` — cross-package thinking guides.
```bash
python3 ./.trellis/scripts/get_context.py --mode packages # list packages / layers
```
**When to update spec**: new pattern/convention found · bug-fix prevention to codify · new technical decision.
### Task System
Every task has its own directory under `.trellis/tasks/{MM-DD-name}/` holding `task.json`, `prd.md`, optional `design.md`, optional `implement.md`, optional `research/`, and context manifests (`implement.jsonl`, `check.jsonl`) for sub-agent-capable platforms.
```bash
# Task lifecycle
python3 ./.trellis/scripts/task.py create "<title>" [--slug <name>] [--parent <dir>]
python3 ./.trellis/scripts/task.py start <name> # set active task (session-scoped when available)
python3 ./.trellis/scripts/task.py current --source # show active task and source
python3 ./.trellis/scripts/task.py finish # clear active task (triggers after_finish hooks)
python3 ./.trellis/scripts/task.py archive <name> # move to archive/{year-month}/
python3 ./.trellis/scripts/task.py list [--mine] [--status <s>]
python3 ./.trellis/scripts/task.py list-archive
# Code-spec context (injected into implement/check agents via JSONL).
# `implement.jsonl` / `check.jsonl` are seeded on `task create` for sub-agent-capable
# platforms; the AI curates real spec + research entries during planning when needed.
python3 ./.trellis/scripts/task.py add-context <name> <action> <file> <reason>
python3 ./.trellis/scripts/task.py list-context <name> [action]
python3 ./.trellis/scripts/task.py validate <name>
# Task metadata
python3 ./.trellis/scripts/task.py set-branch <name> <branch>
python3 ./.trellis/scripts/task.py set-base-branch <name> <branch> # PR target
python3 ./.trellis/scripts/task.py set-scope <name> <scope>
# Hierarchy (parent/child)
python3 ./.trellis/scripts/task.py add-subtask <parent> <child>
python3 ./.trellis/scripts/task.py remove-subtask <parent> <child>
# PR creation
python3 ./.trellis/scripts/task.py create-pr [name] [--dry-run]
```
> Run `python3 ./.trellis/scripts/task.py --help` to see the authoritative, up-to-date list.
**Current-task mechanism**: `task.py create` creates the task directory and (when session identity is available) auto-sets the per-session active-task pointer so the planning breadcrumb fires immediately. `task.py start` writes the same pointer (idempotent if already set) and flips `task.json.status` from `planning` to `in_progress`. State is stored under `.trellis/.runtime/sessions/`. If no context key is available from hook input, `TRELLIS_CONTEXT_ID`, or a platform-native session environment variable, there is no active task and `task.py start` fails with a session identity hint. `task.py finish` deletes the current session file (status unchanged). `task.py archive <task>` writes `status=completed`, moves the directory to `archive/`, and deletes any runtime session files that still point at the archived task.
### Workspace System
Records every AI session for cross-session tracking under `.trellis/workspace/<developer>/`.
- `journal-N.md` — session log. **Max 2000 lines per file**; a new `journal-(N+1).md` is auto-created when exceeded.
- `index.md` — personal index (total sessions, last active).
```bash
python3 ./.trellis/scripts/add_session.py --title "Title" --commit "hash" --summary "Summary"
```
### Context Script
```bash
python3 ./.trellis/scripts/get_context.py # full session runtime
python3 ./.trellis/scripts/get_context.py --mode packages # available packages + spec layers
python3 ./.trellis/scripts/get_context.py --mode phase --step <X.Y> # detailed guide for a workflow step
```
---
<!--
WORKFLOW-STATE BREADCRUMB CONTRACT (read this before editing the tag blocks below)
The [workflow-state:STATUS] blocks embedded in the ## Phase Index section
below are the SINGLE source of truth for the per-turn `<workflow-state>`
breadcrumb that every supported AI platform's UserPromptSubmit hook
reads. inject-workflow-state.py (Python platforms) and
inject-workflow-state.js (OpenCode plugin) only parse them — there is no
fallback dict baked into the scripts after v0.5.0-rc.0.
STATUS charset: [A-Za-z0-9_-]+. When the hook can't find a tag, it
degrades to a generic "Refer to workflow.md for current step." line —
intentionally visible so users notice and fix a broken workflow.md.
INVARIANT (test/regression.test.ts):
Every workflow-walkthrough step marked `[required · once]` must have a
matching enforcement line in its phase's [workflow-state:*] block. The
breadcrumb is the only per-turn channel; if a mandatory step isn't
mentioned there, the AI silently skips it (Phase 1 planning gate
skip and Phase 3.4 commit skip both manifested via this gap).
TAG ↔ PHASE scoping:
[workflow-state:no_task] → no active task; before Phase 1
[workflow-state:planning] → all of Phase 1 (status='planning')
[workflow-state:planning-inline] → Codex inline variant of Phase 1
[workflow-state:in_progress] → Phase 2 + Phase 3.2-3.4
(status stays 'in_progress' from
task.py start until task.py archive)
[workflow-state:in_progress-inline] → Codex inline variant of Phase 2/3
[workflow-state:completed] → currently DEAD: cmd_archive flips
status and moves the dir in the same
call, so the resolver loses the
pointer (block kept for a future
explicit in_progress→completed
transition)
Editing checklist:
- When you change a [workflow-state:STATUS] block, also check the
matching phase's `[required · once]` walkthrough steps for sync
- Run `trellis update` after editing to push the new bodies to
downstream user projects (block-level managed replacement)
- Full runtime contract:
.trellis/spec/cli/backend/workflow-state-contract.md
-->
## Phase Index
```
Phase 1: Plan → classify, get task-creation consent, then write planning artifacts
Phase 2: Execute → implement only after task status is in_progress
Phase 3: Finish → verify, update spec, commit, and wrap up
```
### Request Triage
- Simple conversation or small task: ask only whether this turn should create a Trellis task. If the user says no, skip Trellis for this session.
- Complex task: ask whether you may create a Trellis task and enter planning. If the user says no, do not do broad inline implementation; explain, clarify scope, or suggest a smaller split.
- User approval to create a task is not approval to start implementation. Planning still happens first.
### Planning Artifacts
- `prd.md` — requirements, constraints, and acceptance criteria. Do not put technical design or execution checklists here.
- `design.md` — technical design for complex tasks: boundaries, contracts, data flow, tradeoffs, compatibility, rollout / rollback shape.
- `implement.md` — execution plan for complex tasks: ordered checklist, validation commands, review gates, and rollback points.
- `implement.jsonl` / `check.jsonl` — spec and research manifests for sub-agent context. They do not replace `implement.md`.
- Lightweight tasks may be PRD-only. Complex tasks must have `prd.md`, `design.md`, and `implement.md` before `task.py start`.
### Parent / Child Task Trees
Use a parent task when one user request contains several independently verifiable deliverables. The parent task owns the source requirement set, the task map, cross-child acceptance criteria, and final integration review; it normally should not be the implementation target unless it also has direct work.
Use child tasks for deliverables that can be planned, implemented, checked, and archived independently. Parent/child structure is not a dependency system: if one child must wait for another, write that ordering in the child `prd.md` / `implement.md` and keep each child's acceptance criteria testable.
Create new children with `task.py create "<title>" --slug <name> --parent <parent-dir>`. Link existing tasks with `task.py add-subtask <parent> <child>`, and unlink mistakes with `task.py remove-subtask <parent> <child>`.
<!-- Per-turn breadcrumb: shown when there is no active task (before Phase 1) -->
[workflow-state:no_task]
No active task. First classify the current turn and ask for task-creation consent before creating any Trellis task.
Simple conversation / small task: ask only whether this turn should create a Trellis task. If the user says no, skip Trellis for this session.
Complex task: ask the user if you can create a Trellis task and enter the planning phase. If the user says no, explain, clarify scope, or suggest a smaller split.
[/workflow-state:no_task]
### Phase 1: Plan
- 1.0 Create task `[required · once]` (only after task-creation consent)
- 1.1 Requirement exploration `[required · repeatable]` (`prd.md`; complex tasks also need `design.md` + `implement.md`)
- 1.2 Research `[optional · repeatable]`
- 1.3 Configure context `[required · once]` — Claude Code, Cursor, OpenCode, Codex, Kiro, Gemini, Qoder, CodeBuddy, Copilot, Droid, Pi (sub-agent-dispatch platforms only; inline platforms skip)
- 1.4 Activate task `[required · once]` (review gate, then `task.py start`; status → in_progress)
- 1.5 Completion criteria
<!-- Per-turn breadcrumb: shown throughout Phase 1 (status='planning') -->
[workflow-state:planning]
Load `trellis-brainstorm`; stay in planning.
Lightweight: `prd.md` can be enough. Complex: finish `prd.md`, `design.md`, and `implement.md`; ask for review before `task.py start`.
Multi-deliverable scope: consider a parent task plus independently verifiable child tasks; dependencies must be written in child artifacts, not implied by tree position.
Sub-agent mode: curate `implement.jsonl` and `check.jsonl` as spec/research manifests before start.
[/workflow-state:planning]
<!-- Per-turn breadcrumb: shown throughout Phase 1 when codex.dispatch_mode=inline.
Codex-only opt-in alternate to [workflow-state:planning]. The main agent
edits code directly in Phase 2, so jsonl curation is skipped —
the inline workflow loads `trellis-before-dev` instead of injecting JSONL
into a sub-agent. -->
[workflow-state:planning-inline]
Load `trellis-brainstorm`; stay in planning.
Lightweight: `prd.md` can be enough. Complex: finish `prd.md`, `design.md`, and `implement.md`; ask for review before `task.py start`.
Multi-deliverable scope: consider a parent task plus independently verifiable child tasks; dependencies must be written in child artifacts, not implied by tree position.
Inline mode: skip jsonl curation; Phase 2 reads artifacts/specs via `trellis-before-dev`.
[/workflow-state:planning-inline]
### Phase 2: Execute
- 2.1 Implement `[required · repeatable]`
- 2.2 Quality check `[required · repeatable]`
- 2.3 Rollback `[on demand]`
<!-- Per-turn breadcrumb: shown while status='in_progress'.
Scope: all of Phase 2 + Phase 3.2-3.4 (status stays 'in_progress' from
task.py start until task.py archive; only archive flips it). The body
therefore must cover every required step from implementation through
commit, including Phase 3.3 spec update and Phase 3.4 commit. -->
Sub-agent dispatch protocol applies to all platforms and all sub-agents, including class-2 Codex/Copilot/Gemini/Qoder and `trellis-research`: every dispatch prompt starts with `Active task: <task path from task.py current>` before role-specific instructions.
[workflow-state:in_progress]
Tools: `trellis-implement` / `trellis-research` are sub-agent types only (Task/Agent tool, NOT Skill; there is no skill by these names). `trellis-update-spec` is a skill. `trellis-check` exists as both; prefer the Agent form when verifying after code changes.
Flow: `trellis-implement` -> `trellis-check` -> `trellis-update-spec` -> commit (Phase 3.4) -> `/trellis:finish-work`.
Main-session default: dispatch implement/check sub-agents. Sub-agent self-exemption: if already running as `trellis-implement`, do NOT spawn another `trellis-implement` or `trellis-check`; if already running as `trellis-check`, do NOT spawn another `trellis-check` or `trellis-implement`. Dispatch is main session only.
Dispatch prompt starts with `Active task: <task path from task.py current>`. Read context: jsonl entries -> `prd.md` -> `design.md if present` -> `implement.md if present`.
[/workflow-state:in_progress]
<!-- Per-turn breadcrumb: shown while status='in_progress' when
codex.dispatch_mode=inline. Codex-only opt-in alternate to
[workflow-state:in_progress]. The main session edits code directly
instead of dispatching sub-agents. -->
[workflow-state:in_progress-inline]
Flow: `trellis-before-dev` -> edit -> `trellis-check` -> validation -> `trellis-update-spec` -> commit (Phase 3.4) -> `/trellis:finish-work`.
Do not dispatch implement/check sub-agents in inline mode.
Read context: `prd.md` -> `design.md if present` -> `implement.md if present`, plus relevant spec/research loaded by skills.
[/workflow-state:in_progress-inline]
### Phase 3: Finish
- 3.2 Debug retrospective `[on demand]`
- 3.3 Spec update `[required · once]`
- 3.4 Commit changes `[required · once]`
- 3.5 Wrap-up reminder
> Note: step 3.1 was folded into 2.2 (last-iteration full-scope check) and 3.4 (commit preamble). Numbering kept stable to avoid breaking external references.
<!-- Per-turn breadcrumb: shown while status='completed'.
Currently DEAD in normal flow: cmd_archive writes status='completed' in
the same call that moves the task dir to archive/, so the active-task
resolver loses the pointer and the hook never fires on archived tasks.
Block preserved for a future status-transition redesign (e.g. an
explicit in_progress→completed command). Edit through the same spec
channel as the live blocks. -->
[workflow-state:completed]
Code committed. Run `/trellis:finish-work`; if dirty, return to Phase 3.4 first.
[/workflow-state:completed]
### Rules
1. Identify which Phase you're in, then continue from the next step there
2. Run steps in order inside each Phase; `[required]` steps can't be skipped
3. Phases can roll back (e.g., Execute reveals a prd defect → return to Plan to fix, then re-enter Execute)
4. Steps tagged `[once]` are skipped if the output already exists; don't re-run
5. Artifact presence informs the next step; missing `design.md` / `implement.md` is valid for lightweight tasks and incomplete planning for complex tasks.
### Active Task Routing
When a user request matches one of these intents inside an active task, route first, then load the detailed phase step if needed.
[Claude Code, Cursor, OpenCode, codex-sub-agent, Kiro, Gemini, Qoder, CodeBuddy, Copilot, Droid, Pi]
- Planning or unclear requirements -> `trellis-brainstorm`.
- `in_progress` implementation/check -> dispatch `trellis-implement` / `trellis-check`.
- Repeated debugging -> `trellis-break-loop`; spec updates -> `trellis-update-spec`.
[/Claude Code, Cursor, OpenCode, codex-sub-agent, Kiro, Gemini, Qoder, CodeBuddy, Copilot, Droid, Pi]
[codex-inline, Kilo, Antigravity, Devin]
- Planning or unclear requirements -> `trellis-brainstorm`.
- Before editing -> `trellis-before-dev`; after editing -> `trellis-check`.
- Repeated debugging -> `trellis-break-loop`; spec updates -> `trellis-update-spec`.
[/codex-inline, Kilo, Antigravity, Devin]
### Guardrails
- Task creation approval is not implementation approval; implementation waits for `task.py start` after artifact review.
- PRD-only is valid for lightweight tasks; complex tasks need `design.md` + `implement.md`.
- Planning must be persisted to task artifacts; checks must run before reporting completion.
### Loading Step Detail
At each step, run this to fetch detailed guidance:
```bash
python3 ./.trellis/scripts/get_context.py --mode phase --step <step>
# e.g. python3 ./.trellis/scripts/get_context.py --mode phase --step 1.1
```
---
## Phase 1: Plan
Goal: classify the request, get task-creation consent when a task is needed, and produce the planning artifacts required before implementation.
#### 1.0 Create task `[required · once]`
Create the task directory only after task-creation consent. The command sets status to `planning`, writes `task.json`, creates a default `prd.md`, and auto-targets the new task when session identity is available:
```bash
python3 ./.trellis/scripts/task.py create "<task title>" --slug <name>
```
`--slug` is the human-readable name only. Do **not** include the `MM-DD-` date prefix; `task.py create` adds that prefix automatically.
For task trees, create the parent task first and then create each child with `--parent <parent-dir>`. Do not start the parent just because children exist; start the child that owns the next independently verifiable deliverable.
After this command succeeds, the per-turn breadcrumb auto-switches to `[workflow-state:planning]`, telling the AI to stay in planning.
Run only `create` here — do not also run `start`. `start` flips status to `in_progress`, which switches the breadcrumb to the implementation phase before planning artifacts are reviewed. Save `start` for step 1.4.
Skip when `python3 ./.trellis/scripts/task.py current --source` already points to a task.
#### 1.1 Requirement exploration `[required · repeatable]`
Load the `trellis-brainstorm` skill and explore requirements interactively with the user per the skill's guidance.
The brainstorm skill will guide you to:
- Ask one question at a time
- Prefer researching over asking the user
- Prefer offering options over open-ended questions
- Update `prd.md` immediately after each user answer
- Split large scopes into a parent task plus child tasks when the deliverables can be verified independently
- Keep `prd.md` focused on requirements and acceptance criteria
- For complex tasks, produce `design.md` and `implement.md` before implementation starts
When considering a parent/child split:
- Use a parent task when one request contains several independently verifiable deliverables.
- Parent tasks own source requirements, child-task mapping, cross-child acceptance criteria, and final integration review.
- Child tasks own actual deliverables that can be planned, implemented, checked, and archived independently.
- Parent/child structure is not a dependency system. If child B depends on child A, write that ordering in child B's `prd.md` / `implement.md`.
- Start the child task that owns the next deliverable. Do not start the parent unless the parent itself has direct implementation work.
Return to this step whenever requirements change and revise the relevant artifact.
#### 1.2 Research `[optional · repeatable]`
Research can happen at any time during requirement exploration. It isn't limited to local code — you can use any available tool (MCP servers, skills, web search, etc.) to look up external information, including third-party library docs, industry practices, API references, etc.
[Claude Code, Cursor, OpenCode, codex-sub-agent, Kiro, Gemini, Qoder, CodeBuddy, Copilot, Droid, Pi]
Spawn the research sub-agent:
- **Agent type**: `trellis-research`
- **Task description**: Research <specific question>
- **Key requirement**: Research output MUST be persisted to `{TASK_DIR}/research/`
[/Claude Code, Cursor, OpenCode, codex-sub-agent, Kiro, Gemini, Qoder, CodeBuddy, Copilot, Droid, Pi]
[codex-inline, Kilo, Antigravity, Devin]
Do the research in the main session directly and write findings into `{TASK_DIR}/research/`. (For `codex-inline` this avoids the `fork_turns="none"` isolation that prevents `trellis-research` sub-agents from resolving the active task path.)
[/codex-inline, Kilo, Antigravity, Devin]
**Research artifact conventions**:
- One file per research topic (e.g. `research/auth-library-comparison.md`)
- Record third-party library usage examples, API references, version constraints in files
- Note relevant spec file paths you discovered for later reference
Brainstorm and research can interleave freely — pause to research a technical question, then return to talk with the user.
**Key principle**: Research output must be written to files, not left only in the chat. Conversations get compacted; files don't.
#### 1.3 Configure context `[required · once]`
[Claude Code, Cursor, OpenCode, codex-sub-agent, Kiro, Gemini, Qoder, CodeBuddy, Copilot, Droid, Pi]
Curate `implement.jsonl` and `check.jsonl` so the Phase 2 sub-agents get the right spec/research context. These files were seeded on `task create` with a single self-describing `_example` line; your job here is to fill in real entries.
**Location**: `{TASK_DIR}/implement.jsonl` and `{TASK_DIR}/check.jsonl` (already exist).
**Format**: one JSON object per line — `{"file": "<path>", "reason": "<why>"}`. Paths are repo-root relative.
**What to put in**:
- **Spec files** — `.trellis/spec/<package>/<layer>/index.md` and any specific guideline files (`error-handling.md`, `conventions.md`, etc.) relevant to this task
- **Research files** — `{TASK_DIR}/research/*.md` that the sub-agent will need to consult
**What NOT to put in**:
- Code files (`src/**`, `packages/**/*.ts`, etc.) — those are read by the sub-agent during implementation, not pre-registered here
- Files you're about to modify — same reason
**Split between the two files**:
- `implement.jsonl` → specs + research the implement sub-agent needs to write code correctly
- `check.jsonl` → specs for the check sub-agent (quality guidelines, check conventions, same research if needed)
These manifests do not replace `implement.md`. `implement.md` is the human-readable execution plan for a complex task; jsonl files only list context files to inject or load.
**How to discover relevant specs**:
```bash
python3 ./.trellis/scripts/get_context.py --mode packages
```
Lists every package + its spec layers with paths. Pick the entries that match this task's domain.
**How to append entries**:
Either edit the jsonl file directly in your editor, or use:
```bash
python3 ./.trellis/scripts/task.py add-context "$TASK_DIR" implement "<path>" "<reason>"
python3 ./.trellis/scripts/task.py add-context "$TASK_DIR" check "<path>" "<reason>"
```
Delete the seed `_example` line once real entries exist (optional — it's skipped automatically by consumers).
Skip when: `implement.jsonl` and `check.jsonl` have agent-curated entries (the seed row alone doesn't count).
[/Claude Code, Cursor, OpenCode, codex-sub-agent, Kiro, Gemini, Qoder, CodeBuddy, Copilot, Droid, Pi]
[codex-inline, Kilo, Antigravity, Devin]
Skip this step. Context is loaded directly by the `trellis-before-dev` skill in Phase 2.
[/codex-inline, Kilo, Antigravity, Devin]
#### 1.4 Activate task `[required · once]`
After artifact review, flip the task status to `in_progress`:
```bash
python3 ./.trellis/scripts/task.py start <task-dir>
```
For lightweight tasks, `prd.md` can be enough. For complex tasks, `prd.md`, `design.md`, and `implement.md` must exist and be reviewed before start. On sub-agent-capable platforms, curate jsonl manifests when extra spec or research context is needed; seed-only manifests are tolerated by consumers.
After this command succeeds, the breadcrumb auto-switches to `[workflow-state:in_progress]`, and the rest of Phase 2 / 3 follows.
If `task.py start` errors with a session-identity message (no context key from hook input, `TRELLIS_CONTEXT_ID`, or platform-native session env), follow the hint in the error to set up session identity, then retry.
#### 1.5 Completion criteria
| Condition | Required |
|------|:---:|
| `prd.md` exists | ✅ |
| User confirms task should enter implementation | ✅ |
| `task.py start` has been run (status = in_progress) | ✅ |
| `research/` has artifacts (complex tasks) | recommended |
| `design.md` exists (complex tasks) | ✅ |
| `implement.md` exists (complex tasks) | ✅ |
[Claude Code, Cursor, OpenCode, codex-sub-agent, Kiro, Gemini, Qoder, CodeBuddy, Copilot, Droid, Pi]
| `implement.jsonl` / `check.jsonl` curated when extra spec or research context is needed | recommended |
[/Claude Code, Cursor, OpenCode, codex-sub-agent, Kiro, Gemini, Qoder, CodeBuddy, Copilot, Droid, Pi]
---
## Phase 2: Execute
Goal: turn reviewed planning artifacts into code that passes quality checks.
#### 2.1 Implement `[required · repeatable]`
[Claude Code, Cursor, OpenCode, Gemini, Qoder, CodeBuddy, Copilot, Droid, Pi]
Spawn the implement sub-agent:
- **Agent type**: `trellis-implement`
- **Task description**: Implement the reviewed task artifacts, consulting materials under `{TASK_DIR}/research/`; finish by running project lint and type-check
- **Dispatch prompt guard**: Tell the spawned agent it is already the `trellis-implement` sub-agent and must implement directly, not spawn another `trellis-implement` / `trellis-check`.
The platform hook/plugin auto-handles:
- Reads `implement.jsonl` and injects referenced spec/research files into the agent prompt
- Injects `prd.md`, `design.md` if present, and `implement.md` if present
[/Claude Code, Cursor, OpenCode, Gemini, Qoder, CodeBuddy, Copilot, Droid, Pi]
[codex-sub-agent]
Spawn the implement sub-agent:
- **Agent type**: `trellis-implement`
- **Task description**: Implement the reviewed task artifacts, consulting materials under `{TASK_DIR}/research/`; finish by running project lint and type-check
- **Dispatch prompt guard**: The prompt MUST start with `Active task: <task path>`, then explicitly say the spawned agent is already `trellis-implement` and must implement directly without spawning another `trellis-implement` / `trellis-check`.
The Codex sub-agent definition auto-handles the context load requirement:
- Resolves the active task with `task.py current --source`, then reads `prd.md`, `design.md` if present, and `implement.md` if present
- Reads `implement.jsonl` and requires the agent to load each referenced spec/research file before coding
[/codex-sub-agent]
[Kiro]
Spawn the implement sub-agent:
- **Agent type**: `trellis-implement`
- **Task description**: Implement the reviewed task artifacts, consulting materials under `{TASK_DIR}/research/`; finish by running project lint and type-check
- **Dispatch prompt guard**: Tell the spawned agent it is already the `trellis-implement` sub-agent and must implement directly, not spawn another `trellis-implement` / `trellis-check`.
The platform prelude auto-handles the context load requirement:
- Reads `implement.jsonl` and injects referenced spec/research files into the agent prompt
- Injects `prd.md`, `design.md` if present, and `implement.md` if present
[/Kiro]
[codex-inline, Kilo, Antigravity, Devin]
1. Load the `trellis-before-dev` skill to read project guidelines
2. Read `{TASK_DIR}/prd.md`, then `design.md` if present, then `implement.md` if present
3. Consult materials under `{TASK_DIR}/research/`
4. Implement the code per reviewed artifacts
5. Run project lint and type-check
[/codex-inline, Kilo, Antigravity, Devin]
#### 2.2 Quality check `[required · repeatable]`
[Claude Code, Cursor, OpenCode, codex-sub-agent, Kiro, Gemini, Qoder, CodeBuddy, Copilot, Droid, Pi]
Spawn the check sub-agent:
- **Agent type**: `trellis-check`
- **Task description**: Review all code changes against specs and task artifacts; fix any findings directly; ensure lint and type-check pass
- **Dispatch prompt guard**: Tell the spawned agent it is already the `trellis-check` sub-agent and must review/fix directly, not spawn another `trellis-check` / `trellis-implement`.
The check agent's job:
- Review code changes against specs
- Review code changes against `prd.md`, `design.md` if present, and `implement.md` if present
- Auto-fix issues it finds
- Run lint and typecheck to verify
[/Claude Code, Cursor, OpenCode, codex-sub-agent, Kiro, Gemini, Qoder, CodeBuddy, Copilot, Droid, Pi]
[codex-inline, Kilo, Antigravity, Devin]
Load the `trellis-check` skill and verify the code per its guidance:
- Spec compliance
- lint / type-check / tests
- Cross-layer consistency (when changes span layers)
If issues are found → fix → re-check, until green.
[/codex-inline, Kilo, Antigravity, Devin]
**Final pass (before Phase 3.4 commit)**: the last 2.2 of a task must run full-scope, not just on the latest implement chunk. List all affected packages with `python3 ./.trellis/scripts/get_context.py --mode packages`, then load each package's spec index Quality Check section. This catches cross-layer / multi-package issues a mid-iteration local 2.2 cannot.
#### 2.3 Rollback `[on demand]`
- `check` reveals a prd defect → return to Phase 1, fix `prd.md`, then redo 2.1
- Implementation went wrong → revert code, redo 2.1
- Need more research → research (same as Phase 1.2), write findings into `research/`
---
## Phase 3: Finish
Goal: ensure code quality, capture lessons, record the work.
#### 3.2 Debug retrospective `[on demand]`
If this task involved repeated debugging (the same issue was fixed multiple times), load the `trellis-break-loop` skill to:
- Classify the root cause
- Explain why earlier fixes failed
- Propose prevention
The goal is to capture debugging lessons so the same class of issue doesn't recur.
#### 3.3 Spec update `[required · once]`
Load the `trellis-update-spec` skill and review whether this task produced new knowledge worth recording:
- Newly discovered patterns or conventions
- Pitfalls you hit
- New technical decisions
Update the docs under `.trellis/spec/` accordingly. Even if the conclusion is "nothing to update", walk through the judgment.
#### 3.4 Commit changes `[required · once]`
**Spec-sync preamble**: before drafting commits, ask: did this task fix a bug or surface non-obvious knowledge that should land in `.trellis/spec/` so future-you (or future-AI) doesn't repeat the mistake? If yes, return to Phase 3.3 first — spec writes belong in the same task's commit batch, not as a forgotten follow-up.
The AI drives a batched commit of this task's code changes so `/finish-work` can run cleanly afterwards. Goal: produce work commits FIRST, then bookkeeping (archive + journal) commits land after — never interleaved.
**Step-by-step**:
1. **Inspect dirty state**:
```bash
git status --porcelain
```
Snapshot every dirty path. If the working tree is clean, skip to 3.5.
2. **Learn commit style** from recent history (so drafted messages blend in):
```bash
git log --oneline -5
```
Note the prefix convention (`feat:` / `fix:` / `chore:` / `docs:` ...), language (中文/English), and length style.
3. **Classify dirty files into two groups**:
- **AI-edited this session** — files you wrote/edited via Edit/Write/Bash tool calls in this session. You know what changed and why.
- **Unrecognized** — dirty files you did NOT touch this session (could be the user's manual edits, leftover WIP from a previous session, or unrelated work). Do NOT silently include these.
4. **Draft a commit plan**. Group AI-edited files into logical commits (1 commit per coherent change unit, not 1 commit per file). Each entry: `<commit message>` + file list. List unrecognized files separately at the bottom.
5. **Present the plan once, ask for one-shot confirmation**. Format:
```
Proposed commits (in order):
1. <message>
- <file>
- <file>
2. <message>
- <file>
Unrecognized dirty files (NOT in any commit — confirm include/exclude):
- <file>
- <file>
Reply 'ok' / '行' to execute. Reply with edits, or '我自己来' / 'manual' to abort.
```
6. **On confirmation**: run `git add <files>` + `git commit -m "<msg>"` for each batch in order. Do not amend. Do not push.
7. **On rejection** (user replies "不行" / "我自己来" / "manual" / any pushback on the plan): stop. Do not attempt a second plan. The user will commit by hand; you skip ahead to 3.5 once they confirm.
**Rules**:
- No `git commit --amend` anywhere — three-stage three-commit flow (work commits → archive commit → journal commit).
- Never push to remote in this step.
- If the user wants different message wording but accepts the file grouping, edit the message and re-confirm once — but if they reject the grouping, exit to manual mode.
- The batched plan is one prompt; do not prompt per commit.
#### 3.5 Wrap-up reminder
After the above, remind the user they can run `/finish-work` to wrap up (archive the task, record the session).
---
## Customizing Trellis (for forks)
This section is for developers who want to modify the Trellis workflow itself. All customization is done by editing this file; the scripts are parsers only.
### Changing what a step means
Edit the corresponding step's walkthrough body in the Phase 1 / 2 / 3 sections above. Critical invariants:
- No active task must triage first and ask for task-creation consent before creating a Trellis task.
- Planning must distinguish lightweight PRD-only tasks from complex tasks that require `prd.md`, `design.md`, and `implement.md` before start.
- Every required execution path must keep the Phase 3.4 commit reminder reachable before `/trellis:finish-work`.
All tag blocks live in the `## Phase Index` section above, immediately after each phase summary:
| Scope | Corresponding tag |
|---|---|
| No active task (before Phase 1) | `[workflow-state:no_task]` (after the Phase Index ASCII art) |
| All of Phase 1 (task created → ready for implementation) | `[workflow-state:planning]` (after Phase 1 summary) |
| Codex inline Phase 1 | `[workflow-state:planning-inline]` |
| Phase 2 + Phase 3.2–3.4 (implementation + check + wrap-up) | `[workflow-state:in_progress]` (after Phase 2 summary) |
| Codex inline Phase 2 + Phase 3.2–3.4 | `[workflow-state:in_progress-inline]` |
| After Phase 3.5 (archived) | `[workflow-state:completed]` (after Phase 3 summary; **currently DEAD**) |
### Changing the per-turn prompt text
Directly edit the body of the corresponding `[workflow-state:STATUS]` block. After editing, run `trellis update` (if you're a template maintainer) or restart your AI session (if you're customizing your own project) — no script changes required.
### Adding a custom status
Add a new block:
```
[workflow-state:my-status]
your per-turn prompt text
[/workflow-state:my-status]
```
Constraints:
- STATUS charset: `[A-Za-z0-9_-]+` (underscores and hyphens allowed, e.g. `in-review`, `blocked-by-team`)
- A lifecycle hook must write `task.json.status` to your custom value, otherwise the tag is never read
- Lifecycle hooks live in `task.json.hooks.after_*` and bind to one of `after_create / after_start / after_finish / after_archive`
### Adding a lifecycle hook
Add a `hooks` field to your `task.json`:
```json
{
"hooks": {
"after_finish": [
"your-script-or-command-here"
]
}
}
```
Supported events: `after_create / after_start / after_finish / after_archive`. Note that `after_finish` ≠ a status change (it only clears the active-task pointer); use `after_archive` for "task is done" notifications.
### Full contract
For the workflow state machine's runtime contract, the locations of all status writers, pseudo-statuses (`no_task` / `stale_<source_type>`), the hook reachability matrix, and other deep details, see:
- `.trellis/spec/cli/backend/workflow-state-contract.md` — runtime contract + writer table + test invariants
- `.trellis/scripts/inject-workflow-state.py` — actual parser (reads workflow.md only, no embedded text)
.trellis/workspace/boos4721/index.md
+40
View File
@@ -0,0 +1,40 @@
# Workspace Index - boos4721
> Journal tracking for AI development sessions.
---
## Current Status
<!-- @@@auto:current-status -->
- **Active File**: `journal-1.md`
- **Total Sessions**: 0
- **Last Active**: -
<!-- @@@/auto:current-status -->
---
## Active Documents
<!-- @@@auto:active-documents -->
| File | Lines | Status |
|------|-------|--------|
| `journal-1.md` | ~0 | Active |
<!-- @@@/auto:active-documents -->
---
## Session History
<!-- @@@auto:session-history -->
| # | Date | Title | Commits | Branch |
|---|------|-------|---------|--------|
<!-- @@@/auto:session-history -->
---
## Notes
- Sessions are appended to journal files
- New journal file created when current exceeds 2000 lines
- Use `add_session.py` to record sessions
.trellis/workspace/boos4721/journal-1.md
+7
View File
@@ -0,0 +1,7 @@
# Journal - boos4721 (Part 1)
> AI development session journal
> Started: 2026-06-20
---
.trellis/workspace/index.md
+125
View File
@@ -0,0 +1,125 @@
# Workspace Index
> Records of all AI Agent work records across all developers
---
## Overview
This directory tracks records for all developers working with AI Agents on this project.
### File Structure
```
workspace/
|-- index.md # This file - main index
+-- {developer}/ # Per-developer directory
|-- index.md # Personal index with session history
|-- tasks/ # Task files
| |-- *.json # Active tasks
| +-- archive/ # Archived tasks by month
+-- journal-N.md # Journal files (sequential: 1, 2, 3...)
```
---
## Active Developers
| Developer | Last Active | Sessions | Active File |
|-----------|-------------|----------|-------------|
| (none yet) | - | - | - |
---
## Getting Started
### For New Developers
Run the initialization script:
```bash
python3 ./.trellis/scripts/init_developer.py <your-name>
```
This will:
1. Create your identity file (gitignored)
2. Create your progress directory
3. Create your personal index
4. Create initial journal file
### For Returning Developers
1. Get your developer name:
```bash
python3 ./.trellis/scripts/get_developer.py
```
2. Read your personal index:
```bash
cat .trellis/workspace/$(python3 ./.trellis/scripts/get_developer.py)/index.md
```
---
## Guidelines
### Journal File Rules
- **Max 2000 lines** per journal file
- When limit is reached, create `journal-{N+1}.md`
- Update your personal `index.md` when creating new files
### Session Record Format
Each session should include:
- Summary: One-line description
- Branch: Which branch the work was done on
- Main Changes: What was modified
- Git Commits: Commit hashes and messages
- Next Steps: What to do next
---
## Session Template
Use this template when recording sessions:
```markdown
## Session {N}: {Title}
**Date**: YYYY-MM-DD
**Task**: {task-name}
**Branch**: `{branch-name}`
### Summary
{One-line summary}
### Main Changes
- {Change 1}
- {Change 2}
### Git Commits
| Hash | Message |
|------|---------|
| `abc1234` | {commit message} |
### Testing
- [OK] {Test result}
### Status
[OK] **Completed** / # **In Progress** / [P] **Blocked**
### Next Steps
- {Next step 1}
- {Next step 2}
```
---
**Language**: All documentation must be written in **English**.
AGENTS.md
+72
View File
@@ -0,0 +1,72 @@
# BoosAPI Engineering Rules
> **AI开发**: 使用 **gpt-5.5**（`api.boos.lat/v1`，key: `sk-boos4721`）进行开发工作。
> 本项目为纯 Rust 项目，无 Node.js 运行时依赖。
## 项目结构
```
boosapi-rs/ ← 根目录（已迁移至此）
├── src/
│ ├── main.rs ← 入口
│ ├── lib.rs
│ ├── config.rs
│ ├── error.rs
│ ├── routes/
│ │ ├── mod.rs
│ │ ├── comfyui_agent.rs ← ComfyUI Agent SSE 聊天
│ │ ├── comfyui/ ← ComfyUI 代理路由
│ │ ├── proxy/ ← OpenAI 兼容代理
│ │ ├── auth/ ← 认证
│ │ └── ...
│ ├── proxy/ ← 代理核心（Conductor/Token Router）
│ ├── services/ ← 后台服务
│ ├── db/ ← 数据库
│ └── transformers/ ← 协议转换
├── dist/web/ ← 前端构建产物（由 Rust 静态 serve）
├── migrations/ ← SQLite 迁移
├── config.toml ← 运行配置
├── Dockerfile
└── Cargo.toml
## ComfyUI Agent
ComfyUI Agent 默认走 **本地模式**：复用本服务自身的 `/v1/*` 路由，bearer 用启动时引导出来的内置 downstream key（`name='comfyui-agent' AND user_id IS NULL`，密钥格式 `sk-comfyui-{uuid_v4_hex}`，同时镜像写入 `settings.builtin_key.comfyui_agent.secret`）。
行为契约：
- **Local（默认）**：`upstream_base` = `http://{server.host}/v1`（host 是 `0.0.0.0` / `::` 时改写为 `127.0.0.1`），bearer = 内置 key；`/api/comfyui-agent/status` 回 `mode: "local"` + `keyName: "comfyui-agent"`
- **FallbackRemote**：当 `BOOSAPI_UPSTREAM_BASE`（trim 后非空）被设置时切换到外部上游；`BOOSAPI_UPSTREAM_KEY` 缺省时仍用内置 key；status 回 `mode: "fallback_remote"` + `keyName: "external"`
- 内置 key 受保护：admin 列表对其 key 字段打码（`••••<后4位>`），删除返 403，禁用（`enabled=false`）返 403；`builtin_key.*` settings 不在 list 中暴露，PUT 返 403
- 启动期 `ensure_comfyui_agent_key` 是幂等的：缺密钥就生成、`enabled=0` 自动恢复并 `tracing::warn!`、settings 与 downstream_api_keys 双向同步
支持的结构化标记（输出由 LLM 生成、由 agent SSE 解析下发）：
- 【CHARACTER】 → 自动调用 gpt-image-2 生成四视图
- 【SCENE】 → 自动生成场景图
- 【TTS】 → 自动调用 TTS API
- 【WORKFLOW】 → 输出 ComfyUI 工作流 JSON
## 运行
```bash
# 开发
cargo run --release
# 环境变量
BOOSAPI_SERVER__HOST=0.0.0.0
BOOSAPI_SERVER__PORT=4000
BOOSAPI_UPSTREAM_BASE=https://api.boos.lat/v1
BOOSAPI_UPSTREAM_KEY=sk-boos4721
BOOSAPI_AUTH__AUTH_TOKEN=change-me-admin-token
```
## 前端
前端为 React SPA，使用 Vite 构建，产物在 `dist/web/`：
- 开发时用 Vite dev server（需 Node.js）
- 生产时由 Rust 后端直接 serve 静态文件
### 登录与会话
- 登录页位于 `src/web/pages/auth/`：`LoginShell` 提供共享外壳，`AdminLoginPage`（token / 账密双模式）与 `UserLoginPage`（账密）分别承担两类受众。OAuth 入口用 `OAuthSlot` 渲染占位区域，**实际行为由后续 change 接入**——当前不要在这里挂任何 onClick / 跳转。
- 会话状态统一走 `src/web/authSession.ts` 的 `commitSession / clearSession / getSessionToken`，受众通过 `'admin' | 'user'` 区分；旧的 `persistAuthSession / clearAuthSession / getAuthToken / hasValidAuthSession`（及 `*UserSession` 同族）保留为 `@deprecated` 薄壳，新代码不要再引用。
- 登录错误文案统一走 `src/web/loginError.ts` 的 `resolveLoginErrorMessage(status, raw)`；新增登录错误请加在该处而不是各自分支里手写。
CLAUDE.md
+89
View File
@@ -0,0 +1,89 @@
# CLAUDE.md
This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
## What this is
BoosAPI is an AI API gateway: an OpenAI/Anthropic/Gemini-compatible proxy with a token-routing/failover engine, a management console (React SPA), embedded ComfyUI workflow surfaces, billing, and payments. Backend is **pure Rust** (axum + sqlx + tokio); there is no Node.js runtime dependency at serving time — Node is only used to build frontend assets.
Project-internal docs are largely in Chinese (`AGENTS.md`, `README.md`); match that when editing them.
## Build & run
The wrapper script `./build-and-run.sh` is the normal entry point (builds frontend + backend, then runs). Key flags:
```bash
./build-and-run.sh --check # cargo check only — fastest verification, no frontend, no run
./build-and-run.sh # dev profile, reuse frontend cache, compile + start
./build-and-run.sh --backend-only # recompile/restart backend, skip Vite
./build-and-run.sh --fast-release # near-prod performance, faster than --release
./build-and-run.sh --production # build + embed frontend/Workflow UI into binary -> dist/production/
```
Cargo profiles: `dev` (default), `release` (LTO, slow), `fast-release` (opt-level 2, no LTO — use for staging verification). Direct cargo also works: `cargo run --release`, `cargo check`.
Config comes from `config.toml` plus env overrides via figment. Env vars use the `BOOSAPI_` prefix with `__` as the nesting separator, e.g. `BOOSAPI_SERVER__PORT=4000`, `BOOSAPI_AUTH__AUTH_TOKEN=...`, `BOOSAPI_PAYMENT__STRIPE_SECRET_KEY=...`. Prefer env vars for all secrets.
## Tests
```bash
cargo test # Rust tests (rstest, wiremock, axum-test, tracing-test)
cargo test <name> # single Rust test by name substring
npm test # web tests: vitest run --root src/web
npm run test:watch # vitest watch
npx vitest run src/web/api.test.ts # single web test file
npm run typecheck # tsc for src/web (app + tests)
```
Rust tests live in `#[cfg(test)]` modules alongside source. Web tests are `src/web/**/*.test.ts(x)`.
## Architecture
### Proxy core (`src/proxy/`) — the heart of the system
Request flow for `/v1/*`: **downstream key auth → token route resolution → channel selection → upstream call (with failover) → protocol transform → response**.
- `token_router/` — `TokenRouter` resolves a requested model name to candidate upstream channels using DB-backed route rows + regex patterns, with a short (2s) in-process cache. Call `invalidate_route_cache()` after mutating routes/channels. Failure cooldown per channel is configurable.
- `conductor/` — `ProxyConductor::execute` drives attempt/failover loop (max 5 attempts). It is decoupled from the DB via injected closures (`select_channel`, `select_next_channel`, `record_success`, `record_failure`, optional `refresh_auth`). `retry_policy.rs` classifies failures into actions: failover, retry-same-channel, refresh-auth, or terminal.
- `executors/`, `providers/`, `surfaces/`, `capabilities/`, `cli_profiles/` — execution backends and provider/capability metadata.
### Protocol transformers (`src/transformers/`)
`openai/`, `anthropic/`, `gemini/` convert between client-facing protocol and upstream protocol around a `canonical/` intermediate form. When adding model/protocol support, work through the canonical layer rather than point-to-point conversions.
### Routes (`src/routes/`)
`mod.rs` assembles the axum router by `.merge()`-ing each module's `routes()` and serves the SPA as a fallback (embedded via `include_dir` in production, or from `dist/web` on disk). `admin/` is the management API; `proxy/` is the OpenAI-compatible entry; `comfyui/`, `comfyui_agent.rs`, `workflow_ui.rs`, `digital_human.rs`, `money_printer.rs`, `picture_agent.rs` are the ComfyUI/creative surfaces.
### Services (`src/services/`)
Background and cross-cutting logic: `billing/`, `payment.rs`, `cron/`, `notification/`, `runtime_auth.rs`, `builtin_keys.rs`, `comfyui_process.rs`, `route_rebuild.rs`. Shared `AppState` (in `src/lib.rs`) is cloned into handlers and holds config, DB pool, HTTP client, and these service handles.
### Database
**SQLite is the only runtime path** — `AppState.db` is `Arc<SqlitePool>`, and all runtime queries target SQLite. The Postgres dependency and `boosapi migrate-sqlite-to-postgres` subcommand exist only to copy/migrate schema+data into Postgres; full Postgres runtime query compatibility is not done. Do not assume queries run against Postgres. Migrations live in `migrations/` (SQLite); `db/schema_compat.rs` applies runtime compatibility fixups after migrations.
## ComfyUI Agent (local-mode contract)
The ComfyUI Agent defaults to **local mode**: it calls this service's own `/v1/*` routes using a bootstrapped built-in downstream key (`name='comfyui-agent' AND user_id IS NULL`, format `sk-comfyui-{uuid_hex}`, mirrored into `settings.builtin_key.comfyui_agent.secret`).
- Local (default): `upstream_base = http://{host}/v1` (host `0.0.0.0`/`::` rewritten to `127.0.0.1`); `/api/comfyui-agent/status` returns `mode: "local"`.
- Fallback-remote: set `BOOSAPI_UPSTREAM_BASE` (non-empty) to use an external upstream; `BOOSAPI_UPSTREAM_KEY` falls back to the built-in key if unset.
- The built-in key is **protected**: admin list masks it (`••••<last4>`), delete/disable return 403, and `builtin_key.*` settings are hidden from list / 403 on PUT. Startup `ensure_comfyui_agent_key` is idempotent (regenerates if missing, re-enables if disabled, keeps settings ↔ downstream_api_keys in sync).
Workflow backend modes (`[comfyui] backend`): `cloud` (Comfy Cloud, default), `runninghub`, `external` (your own ComfyUI), `boosapi` (built-in Rust workflow/API node executor), `docker` (legacy). Workflow UI has separate `cloud` and `external/runninghub` frontend asset bundles — install with `npm run workflow-ui:install:cloud` / `:external`.
## Frontend (two separate apps)
- `src/web/` — management console, React 18 + Vite, built to `dist/web/` and served by the Rust backend. `npm run dev` for HMR, `npm run build:web` to build.
- `website/` — standalone marketing site, **Next.js 16 App Router + React 19**, its own package. Use `npm run website:dev` / `website:build` / `website:typecheck` (these proxy to `npm --prefix website`).
### Auth/session conventions (src/web)
- Session state goes through `authSession.ts`: `commitSession / clearSession / getSessionToken`, bucketed by audience `'admin' | 'user'`. The old `persistAuthSession / clearAuthSession / getAuthToken / hasValidAuthSession` family is `@deprecated` — do not use in new code.
- Login pages are split under `pages/auth/`: `LoginShell` (shared shell) + `AdminLoginPage` (token / account modes) + `UserLoginPage`. OAuth entries render via `OAuthSlot` as placeholders only — do not wire onClick/navigation there.
- Login error text is normalized in `loginError.ts` via `resolveLoginErrorMessage(status, raw)` — add new login errors there, not inline.
## Shared TS/Rust contracts (`src/shared/`)
This directory holds logic mirrored between Rust (`.rs`) and TypeScript (`.ts`/`.js`) — e.g. `tokenRouteContract`, `tokenRoutePatterns`, `modelBrand`, `platformIdentity`, `proxyLogMeta`, `siteInitializationPresets`. When changing a routing/identity contract, keep the Rust and TS sides in sync.
Cargo.lock
Generated
+4234
View File
File diff suppressed because it is too large Load Diff
Cargo.toml
+120
View File
@@ -0,0 +1,120 @@
[package]
name = "boosapi"
version = "1.3.0"
edition = "2021"
description = "AI API Gateway — Rust rewrite of BoosAPI"
[dependencies]
# Web framework
axum = { version = "0.8", features = ["macros", "ws", "multipart"] }
tower = "0.5"
tower-http = { version = "0.6", features = ["cors", "trace", "fs", "compression-gzip"] }
# Async runtime
async-stream = "0.3"
tokio = { version = "1", features = ["full"] }
tokio-util = { version = "0.7", features = ["io"] }
# Database
sqlx = { version = "0.8", features = [
"runtime-tokio",
"sqlite",
"postgres",
"any",
"migrate",
"chrono",
] }
# HTTP client
reqwest = { version = "0.12", features = ["stream", "json", "multipart"] }
url = "2"
lettre = { version = "0.11", default-features = false, features = ["builder", "hostname", "pool", "rustls-tls", "smtp-transport"] }
# Serialization
serde = { version = "1", features = ["derive"] }
serde_json = "1"
serde_yaml = "0.9"
regex = "1"
# Auth
jsonwebtoken = "9"
argon2 = "0.5"
# Config
figment = { version = "0.10", features = ["env", "toml"] }
dotenvy = "0.15"
# Logging
tracing = "0.1"
tracing-subscriber = { version = "0.3", features = ["env-filter", "json"] }
# Error handling
thiserror = "2"
anyhow = "1"
# CLI
clap = { version = "4", features = ["derive"] }
# Time
chrono = { version = "0.4", features = ["serde"] }
# UUID
uuid = { version = "1", features = ["v4", "serde"] }
# Streaming
futures = "0.3"
tokio-tungstenite = { version = "0.26", features = ["rustls-tls-webpki-roots"] }
tokio-stream = "0.1"
bytes = "1"
# Misc
once_cell = "1"
parking_lot = "0.12"
mime = "0.3"
base64 = "0.22"
hmac = "0.12"
sha2 = "0.10"
hex = "0.4"
include_dir = "0.7"
mime_guess = "2"
# Embedded AI agent engine (MIT, vendored as a path dependency). Provides the
# agentic loop, built-in tools, permission callback and cost tracking that the
# Agent Workbench (src/routes/agent.rs) drives through BoosAPI's own provider.
open-agent-sdk = { path = "../open-agent-sdk-rust" }
async-trait = "0.1"
[dev-dependencies]
rstest = "0.24"
wiremock = "0.6"
tracing-test = "0.2"
tempfile = "3"
axum-test = "16"
[profile.release]
opt-level = 3
lto = true
codegen-units = 1
# Faster production-like build for staging/manual verification. This keeps
# optimizations on but avoids the slow LTO + single-codegen-unit release path.
[profile.fast-release]
inherits = "release"
opt-level = 2
lto = false
codegen-units = 256
incremental = true
# Dev-profile speedups: line-tables-only debuginfo (much smaller .debug
# sections → much faster link) and 256 codegen units (more parallelism
# during codegen, slightly worse runtime — fine for dev). Dependencies
# build with no debuginfo at all since we rarely step into them.
[profile.dev]
opt-level = 0
debug = "line-tables-only"
codegen-units = 256
incremental = true
[profile.dev.package."*"]
opt-level = 0
debug = false
DEPLOY.md
+263
View File
@@ -0,0 +1,263 @@
# BoosAPI 部署与环境指南
本文档介绍如何配置和运行 BoosAPI 的开发环境与生产环境。
## 1. 快速参数参考 (CLI Args)
后端二进制文件支持以下命令行参数，优先级高于 `config.toml` 和环境变量：
- `-c, --config <PATH>`: 指定配置文件路径 (默认: `config.toml`)
- `-p, --port <PORT>`: 覆盖监听端口
- `--host <HOST>`: 覆盖监听地址 (如 `0.0.0.0`)
- `--log-level <LEVEL>`: 设置日志级别 (`trace`, `debug`, `info`, `warn`, `error`)
- `--migrate-only`: 仅运行数据库迁移后退出
- `--check-config`: 加载并验证配置后退出
- `-h, --help, -help`: 显示帮助信息
- `-V, --version, -version`: 显示版本信息
示例：
```bash
./boosapi --config prod.toml --port 8080 --log-level warn
# 仅执行迁移
./boosapi --migrate-only
```
---
## 2. 开发环境 (Development)
### 前提条件
- **Rust**: 1.85+ (推荐使用 rustup)
- **Node.js**: 20+ (仅用于前端构建)
- **SQLite**: 系统自带或手动安装
### 步骤
1. **克隆项目**:
```bash
git clone https://github.com/boos/boosapi.git
cd boosapi
```
2. **配置环境**:
复制 `config.toml.example` 并根据需要修改：
```bash
cp config.toml.example config.toml
```
或者直接设置环境变量。
3. **运行前端 (热更新模式)**:
```bash
npm install
# 启动 vite 开发服务器
npm run dev:web
```
默认访问 `http://localhost:5173`。Vite 会将 `/api` 请求代理到后端 `localhost:4000`。
4. **运行后端**:
```bash
# 使用默认配置运行
cargo run
# 推荐：使用 cargo-watch 自动重载
# cargo install cargo-watch
# cargo watch -x run
```
---
## 3. 生产环境 (Production)
### 单二进制生产包
推荐用项目脚本生成生产包：
```bash
./build-and-run.sh --production
```
生产模式会构建主前端和 Workflow UI，并把静态资产嵌入 Rust 二进制。部署目录通常只需要：
```txt
boosapi
config.toml
```
部署目录只需要运行产物和配置。仓库里的 `.agents/`、`.cache/`、本地二进制、Docker tar 包、运行日志等均为本地缓存或构建产物，不应进入发布包。`Cargo.lock` 应保留在仓库中，用于保证生产构建依赖可复现。
启动前检查配置：
```bash
./boosapi --check-config
./boosapi --migrate-only
./boosapi --config config.toml
```
### 推荐：Docker Compose 部署
1. **准备 docker-compose.yml**:
```yaml
services:
boosapi:
image: ghcr.io/boos/boosapi:latest
container_name: boosapi
ports:
- "4000:4000"
volumes:
- ./data:/app/data
- ./config.toml:/app/config.toml
environment:
- BOOSAPI_AUTH__AUTH_TOKEN=your-secure-admin-token
- BOOSAPI_AUTH__JWT_SECRET=your-secure-jwt-secret
- BOOSAPI_DB__URL=sqlite:/app/data/boosapi.db?mode=rwc
restart: unless-stopped
```
2. **启动**:
```bash
docker compose up -d
```
### 传统 Linux 部署 (Systemd + Nginx)
1. **构建前端与后端**:
```bash
# 构建前端
npm run build
# 构建后端
cargo build --release
```
2. **安装**:
将生成的二进制文件 `target/release/boosapi` 和静态资源目录 `dist/web` 拷贝到部署目录 (如 `/opt/boosapi`)。
3. **初始化数据库**:
```bash
/opt/boosapi/boosapi --migrate-only
```
4. **Systemd 配置** (`/etc/systemd/system/boosapi.service`):
```ini
[Unit]
Description=BoosAPI Service
After=network.target
[Service]
Type=simple
User=www-data
WorkingDirectory=/opt/boosapi
ExecStart=/opt/boosapi/boosapi --config /opt/boosapi/config.toml
Restart=always
Environment=BOOSAPI_SERVER__LOG_LEVEL=info
[Install]
WantedBy=multi-user.target
```
5. **Nginx 反向代理配置**:
```nginx
server {
listen 80;
server_name api.yourdomain.com;
location / {
proxy_pass http://127.0.0.1:4000;
proxy_set_header Host $host;
proxy_set_header X-Real-IP $remote_addr;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
proxy_set_header X-Forwarded-Proto $scheme;
# 支持 WebSockets 与 SSE
proxy_http_version 1.1;
proxy_set_header Upgrade $http_upgrade;
proxy_set_header Connection "upgrade";
proxy_buffering off;
proxy_cache off;
}
}
```
---
## 4. 关键配置项
| 配置项 (config.toml) | 环境变量 (ENV) | 说明 |
|-------------------|--------------|------|
| `server.host` | `BOOSAPI_SERVER__HOST` | 后端监听地址 (默认 127.0.0.1) |
| `server.port` | `BOOSAPI_SERVER__PORT` | 后端监听端口 (默认 4000) |
| `auth.auth_token` | `BOOSAPI_AUTH__AUTH_TOKEN` | 管理员登录 Token (静态，必填) |
| `auth.jwt_secret` | `BOOSAPI_AUTH__JWT_SECRET` | JWT 签名密钥 (普通用户，必填) |
| `db.url` | `BOOSAPI_DB__URL` | SQLite 数据库路径 (如 `sqlite:data/boosapi.db`) |
| `comfyui.backend` | `BOOSAPI_COMFYUI__BACKEND` | Workflow 后端：`cloud` / `runninghub` / `external` / `boosapi` / `docker` |
| `comfyui.base_url` | `BOOSAPI_COMFYUI__BASE_URL` | Comfy Cloud、RunningHub 或外部 ComfyUI API 地址 |
| `comfyui.api_key` | `BOOSAPI_COMFYUI__API_KEY` | Workflow 后端 API Key，按后端需要填写 |
| `web_dir` | `BOOSAPI_WEB_DIR` | 前端静态资源目录 (默认 `dist/web`) |
### Workflow 后端配置
BoosAPI 的 `/workflows` 页面使用内嵌 ComfyUI 前端，后端由 `[comfyui]` 选择。
Comfy Cloud：
```toml
[comfyui]
backend = "cloud"
base_url = "https://cloud.comfy.org"
api_key = "your-comfy-cloud-api-key"
```
RunningHub：
```toml
[comfyui]
backend = "runninghub"
base_url = "https://www.runninghub.cn/your-comfy-compatible-endpoint"
api_key = "your-runninghub-api-key"
```
外部完整版 ComfyUI：
```toml
[comfyui]
backend = "external"
base_url = "http://127.0.0.1:8188"
```
BoosAPI API-native 执行器：
```toml
[comfyui]
backend = "boosapi"
```
说明：
- `cloud`、`runninghub`、`external` 和 `boosapi` 模式不要求 BoosAPI 机器有 GPU。
- `docker` / 本地 ComfyUI 模式需要本机有完整模型目录和匹配的 NVIDIA GPU。
- 生产构建应包含 `dist/workflow-ui`、`dist/workflow-ui-cloud`、`dist/workflow-ui-external` 中可用的 Workflow UI 资产；脚本会尽量自动安装与构建。
---
## 5. 运维操作 (Ops)
### 检查配置
在启动前验证配置文件是否正确：
```bash
./boosapi --check-config
```
### 数据库备份
BoosAPI 使用 SQLite，只需备份数据库文件即可：
```bash
cp data/boosapi.db data/boosapi.db.bak
```
如使用 PostgreSQL，请按数据库自身的 `pg_dump` / `pg_restore` 流程备份恢复。
### 查看日志
如果使用 Systemd：
```bash
journalctl -u boosapi -f
```
如果使用 Docker:
```bash
docker logs -f boosapi
```
Dockerfile
+16
View File
@@ -0,0 +1,16 @@
FROM rust:1.83-alpine AS builder
RUN apk add --no-cache musl-dev pkgconfig openssl-dev
WORKDIR /app
COPY Cargo.toml Cargo.lock ./
RUN mkdir src && echo "fn main() {}" > src/main.rs
RUN cargo build --release 2>/dev/null || true
COPY . .
RUN cargo build --release
FROM alpine:3.20
RUN apk add --no-cache ca-certificates tzdata sqlite-libs
WORKDIR /app
COPY --from=builder /app/target/release/boosapi .
COPY --from=builder /app/migrations ./migrations
EXPOSE 4000
CMD ["./boosapi"]
LICENSE
+21
View File
@@ -0,0 +1,21 @@
MIT License
Copyright (c) 2026 Metapi contributors
Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.
README.md
+575 -2
View File
@@ -1,3 +1,576 @@
# metapi
<div align="center">
Meta-layer management and unified proxy for AI API aggregation
# BoosAPI
**AI 聚合网关 + Workflow Studio — 将分散的中转站整合为一个统一入口**
<p>
把你各处注册的 New API / One API / OneHub / DoneHub / Veloera / AnyRouter / Sub2API 等站点，
<br>
汇聚成 <strong>一个 API Key、一个入口</strong>，自动发现模型、智能路由、成本最优。
<br>
<strong>Workflow Studio / 视频助手</strong> — 用内嵌 ComfyUI 前端、多 API 后端和自然语言助手组合图像、视频、语音与文本能力。
<br>
<strong>SaaS 多租户架构</strong>，组织管理、成员邀请、套餐限制，开箱即用。
</p>
<p align="center">
<img alt="Rust" src="https://img.shields.io/badge/Rust-1.85%2B-000000?logo=rust&style=flat">
<img alt="SQLx" src="https://img.shields.io/badge/SQLx-0.8-3E6E93?style=flat">
<img alt="License" src="https://img.shields.io/badge/license-MIT-brightgreen?style=flat">
<img alt="React" src="https://img.shields.io/badge/React-19-61DAFB?logo=react&style=flat">
<img alt="Axum" src="https://img.shields.io/badge/Axum-0.8-3182F6?style=flat">
</p>
<p align="center">
<a href="README.md"><strong>中文</strong></a> |
<a href="README_EN.md">English</a> |
<a href="DEPLOY.md">部署指南</a>
</p>
</div>
---
## 📖 介绍
现在 AI 生态里出现了越来越多基于 New API / One API 系列的聚合中转站，要管理多个站点的余额、模型列表和 API 密钥，往往既分散又费时。
**BoosAPI** 作为中转站之上的**元聚合层**，把多个站点统一到 **一个入口**——下游所有工具即可无感接入全部模型。
支持的上游范围：
- **聚合面板**：New API、One API、OneHub、DoneHub、Veloera、AnyRouter、Sub2API
- **通用兼容接口**：OpenAI / Claude / Gemini compatible，cliproxyapi / CPA
- **官方预设**：阿里云、智谱、豆包 Coding Plan、DeepSeek、Moonshot、MiniMax、ModelScope
- **OAuth 连接**：Codex、Claude、Gemini CLI、Antigravity
| 痛点 | BoosAPI 怎么解决 |
|------|-----------------|
| 🔑 每个站点一个 Key，下游配置一堆 | **统一代理入口 + 多下游 Key 策略**，模型自动聚合 |
| 💸 不知道哪个站点最便宜 | **智能路由** 按成本、余额、使用率选最优通道 |
| 🔄 站点挂了手动切换 | **自动故障转移**，失败通道自动冷却并切换 |
| 📊 余额分散各处 | **集中看板** 一目了然，余额不足自动告警 |
| ✅ 每天签到领额度 | **自动签到** 定时执行，奖励自动追踪 |
| 🤷 不知道各站有什么模型 | **自动模型发现**，上游新增模型零配置 |
| 🎨 想编排图像/视频流程但不想跑本地模型 | **Workflow Studio + 对话助手**，直接复用 BoosAPI 模型路由 |
| 👥 多人协作管理中转站 | **组织管理**，成员邀请，角色权限控制 |
| 📋 不同团队需要不同配额 | **套餐系统**，Free/Pro/Enterprise 三级限制 |
## 2026-06 更新重点
- **后台登录收口**：管理员后台只允许使用 `BOOSAPI_AUTH__AUTH_TOKEN` 这类 API Token 登录；普通用户仍使用账号密码登录用户工作台。
- **日志边界清晰**：管理员「使用日志」保留在 `/logs`，系统/程序日志保留在 `/events`；`/api/events` 现在只接受管理员 API Token，普通用户不会再看到运行日志。
- **通知隔离**：普通用户顶部通知只读取用户公告；管理员通知面板继续聚合签到、余额、令牌、代理、状态与公告事件。
- **后台信息架构**：侧栏按接入管理、创作应用、系统管理、我的账户精简；外部监控入口已移除，系统日志入口保留在系统管理分组。
- **运维与 IP 管理**：新增运维监控视图与 IP 管理页面，支持代理质量检测、连接测试、批量操作与更清晰的状态展示。
- **用户自助工作台**：API Key、计费、账户充值、使用记录、工作空间和模型测试统一到用户侧；工作空间支持分页、一键选择和默认预览。
- **Comfy Checkout 充值**：用户先在系统内创建充值记录，再跳转到配置的 Comfy Checkout 链接付款；充值记录会保留用于后续对账。
- **Workflow UI 更新**：`npm run workflow-ui:install:cloud` 会安装当前 Comfy Cloud 前端资产并写入构建元数据，Rust 服务会对 JS/CSS 走 no-cache，避免继续显示旧版本。
- **本地化时间**：前端展示时间优先使用浏览器/UA 时区，后端无时区时间按 UTC 解析后再转成本地显示。
## ✨ 核心功能
### 🎨 Workflow Studio 与视频助手（Rust）
- **自然语言描述脚本**：说想法 → AI 自动提取角色、场景、对白
- **自动生成四视图**：每个角色正/背/左/右 4 角度，调用 gpt-image-2 生成图片
- **场景生成**：自动为每个场景生成配图
- **TTS 语音合成**：对话台词自动转语音
- **Workflow Studio**：内嵌 ComfyUI 前端，可切换 Comfy Cloud、RunningHub、外部 ComfyUI、BoosAPI API-native 执行器或本地 Docker 完整版 ComfyUI
- **远程执行优先**：使用 Comfy Cloud、RunningHub、外部 API 或 BoosAPI 上游路由时，BoosAPI 服务器不需要 GPU
- **外部 ComfyUI 可选代理**：已有独立 ComfyUI 服务时，可通过 `comfyui.base_url` 接入 `/api/comfyui/proxy/*`
- **Rust 后端**（boosapi-rs）：高性能 SSE 流式响应，零 Node.js 运行时依赖
- 侧边栏「视频助手」入口，与聚合网关同一界面
- **默认走本地模式**：复用本服务自身的 `/v1/*` 路由 + 启动时引导出来的内置 downstream key（`comfyui-agent`），开箱即用，无需额外配置
- **回退远端**：设置 `BOOSAPI_UPSTREAM_BASE`（可选 `BOOSAPI_UPSTREAM_KEY`）即切换为外部上游；`/api/comfyui-agent/status` 的 `mode` 字段会反映当前模式
### 🌐 统一代理网关
- 兼容 **OpenAI** 与 **Claude** 下游格式
- 支持 Responses / Chat Completions / Messages / Completions / Embeddings / Images / Models / Files
- SSE 流式传输，自动格式转换
### 🧠 智能路由引擎
- 自动发现所有上游站点的可用模型，**零配置**生成路由表
- 四级成本信号：实测成本 → 配置成本 → 目录参考价 → 默认兜底
- 多通道概率分摊（成本 40% / 余额 30% / 使用率 30%）
- 失败自动冷却（默认 10 分钟），自动切换通道
### 📡 多平台聚合管理
| 平台 | 适配器 |
|------|--------|
| New API | `new-api` |
| One API | `one-api` |
| OneHub | `onehub` |
| DoneHub | `done-hub` |
| Veloera | `veloera` |
| AnyRouter | `anyrouter` |
| Sub2API | `sub2api` |
### 👥 账号与 Token 管理
- 多站点多账号，四级健康状态追踪（healthy / unhealthy / degraded / disabled）
- 凭证加密存储，自动续签，站点联动禁用
### ✅ 自动签到
- Cron 定时执行（默认每日 08:00）
- 智能解析奖励，签到失败自动通知
- 完整签到日志与并发锁防重
### 💰 余额管理
- 定时刷新（默认每小时），收入与消费趋势分析
- 余额兜底估算，凭证过期自动重新登录
### 🔔 告警通知
五种渠道：Webhook / Bark / Server酱 / Telegram Bot / SMTP 邮件
告警场景：余额不足、站点异常、签到失败、代理异常、Token 过期、每日摘要
### 🎮 模型操练场
- 交互式聊天测试，流式/非流式双模式
- 对比不同通道输出
### 👥 SaaS 多租户管理
- **组织管理**：创建组织，每个组织独立管理成员和配额
- **成员邀请**：通过邮件邀请加入组织，支持管理员/成员角色
- **三级套餐**：Free（3人）/ Pro（10人）/ Enterprise（100人）
- **权限控制**：Owner / Admin / Member 三级角色，细粒度权限
- **套餐限制检查**：成员数、API Key 数、日请求量自动限制
- **邀请链接**：带 token 的邀请链接，48 小时有效期
### 🔌 REST API 总览
| 端点 | 方法 | 说明 |
|------|------|------|
| `/api/organizations` | GET/POST | 组织列表 / 创建组织 |
| `/api/organizations/plans` | GET | 可用套餐列表 |
| `/api/organizations/:id` | GET/PATCH | 组织详情 / 更新 |
| `/api/organizations/:id/members` | GET | 成员列表 |
| `/api/organizations/:id/members/:uid` | PATCH/DELETE | 改角色 / 移除成员 |
| `/api/organizations/:id/invitations` | GET/POST | 邀请列表 / 创建邀请 |
| `/api/organizations/:id/invitations/:invId` | DELETE | 撤销邀请 |
| `/api/invitations/:token` | GET | 公开邀请查询 |
| `/api/invitations/:token/accept` | POST | 接受邀请 |
| `/api/users/register` | POST | 注册新用户 |
| `/api/users/login` | POST | 登录获取 JWT |
| `/api/users/me` | GET/PATCH | 个人信息 / 更新 |
| `/api/user-api-keys` | GET/POST | API Key 列表 / 创建 |
---
## 🖥️ 硬件配置建议
BoosAPI 本身是 Rust 网关与管理后台，不在本地跑大模型推理时不需要 GPU。实际硬件主要取决于你是否把图像/视频生成放在本机 ComfyUI 上执行。
| 使用模式 | CPU | 内存 | 磁盘 | GPU |
|----------|-----|------|------|-----|
| 仅网关 / 管理后台 / `/v1/*` 代理 | 2 核起步，4 核推荐 | 2GB 起步，4GB 推荐 | 10GB+ | 不需要 |
| BoosAPI + Workflow UI + 远程模型 API / Comfy Cloud / RunningHub | 4 核推荐 | 4GB 起步，8GB 推荐 | 20-50GB | 不需要 |
| 外部独立 ComfyUI 代理 | 4 核推荐 | 8GB 推荐 | 50GB+ | BoosAPI 机器不需要；ComfyUI 机器按模型需求配置 |
| 本机 Docker / 本地 ComfyUI 轻量文生图 | 4-8 核 | 16GB+ | 100GB+ | NVIDIA 8GB VRAM 勉强，12GB+ 推荐 |
| 本机视频生成 / 数字人 / 大工作流 | 8 核+ | 32GB 起步，64GB 推荐 | 200GB-1TB | NVIDIA 24GB VRAM 起步，48GB+ 更稳 |
推荐的 SaaS 网关部署规格：
```txt
4 核 CPU
8GB 内存
50GB SSD
无需 GPU
```
如果图像、视频、语音能力走 BoosAPI 上游路由、Comfy Cloud、RunningHub 或其他远程 API，本机只负责网关、数据库、Workflow UI 代理、日志和 Workspace 归档，上面这档配置通常足够。只有把 ComfyUI 模型和视频生成放在本机运行时，才需要高显存 NVIDIA GPU。
## 🎛️ Workflow API 后端模式
BoosAPI 的 Workflow 使用内嵌 ComfyUI 前端，后端可按配置切换：
| backend | 用途 |
|---------|------|
| `cloud` | 代理 Comfy Cloud API，适合默认创作、官方订阅模型和稳定执行 |
| `runninghub` | 代理 RunningHub 的 ComfyUI 兼容 API，适合使用 RunningHub 专属插件、工作流和模型 |
| `external` | 代理你自己部署的完整版 ComfyUI |
| `boosapi` | 使用 BoosAPI 自带 Rust Workflow/API 节点执行器 |
| `docker` | 本地完整版 ComfyUI 模式，适合有本地 GPU 和完整模型目录的环境 |
推荐配置是默认 `cloud`，需要 RunningHub 专属插件或模型时切到 `runninghub`。RunningHub 模式会复用 external 兼容前端，并对 `/object_info`、模型库、`/system_stats` 做短期缓存，减少每次打开工作流时的卡顿。
配置示例：
```toml
[comfyui]
backend = "cloud"
base_url = "https://cloud.comfy.org"
api_key = "your-comfy-cloud-api-key"
```
```toml
[comfyui]
backend = "runninghub"
base_url = "https://www.runninghub.cn/your-comfy-compatible-endpoint"
api_key = "your-runninghub-api-key"
```
```toml
[comfyui]
backend = "external"
base_url = "http://127.0.0.1:8188"
```
```toml
[comfyui]
backend = "boosapi"
```
### 将 Comfy 视频节点包装为 BoosAPI `/v1/videos`
ComfyUI/Comfy Cloud 没有 OpenAI 兼容 `/v1/videos`，但 BoosAPI 可以把一个已保存的视频工作流模板包装成统一视频模型：
1. 在工作流页面保存一个真实 Comfy 视频模板，模板需要能被 `POST /prompt` 执行。
2. 模板图里最好保存节点映射：
- `prompt`：提示词节点和字段
- `negativePrompt`：反向提示词节点和字段，可选
- `ratio` / `resolution` / `duration`：画幅、分辨率和时长节点字段，可选
3. 在模型路由里新增一个模型，例如 `comfy-wan-video`。
4. 让该路由的上游地址或实际模型映射指向模板：
- 上游地址：`comfy://<workflow_public_id>`
- 或模型映射：`comfy:<workflow_public_id>`
之后用户可以直接调用：
```bash
curl http://127.0.0.1:4000/v1/videos \
-H "Authorization: Bearer <BoosAPI downstream key>" \
-H "Content-Type: application/json" \
-d '{
"model": "comfy-wan-video",
"prompt": "cinematic product video, smooth camera movement",
"duration": 5,
"ratio": "9:16",
"resolution": "1080p"
}'
```
返回的 `id` 是 Comfy `prompt_id`，可用 `GET /v1/videos/{id}?model=comfy-wan-video` 查询 Comfy history。
> Workflow UI 有 cloud 与 external/runninghub 两套前端资产。开发环境可用 `npm run workflow-ui:install:cloud`、`npm run workflow-ui:install:external` 单独安装；安装脚本会写入 `boosapi-workflow-ui.json` 构建元数据，生产构建会把可用资产嵌入 Rust 二进制。若浏览器「关于」仍显示旧前端版本，请重启 Rust 服务并强刷浏览器缓存。
## 🚀 快速开始
### Docker Compose（推荐）
```bash
mkdir boosapi && cd boosapi
cat > docker-compose.yml << 'EOF'
services:
boosapi:
image: ghcr.io/boos/boosapi:latest
ports:
- "4000:4000"
volumes:
- ./data:/app/data
environment:
BOOSAPI_AUTH__AUTH_TOKEN: ${AUTH_TOKEN?required}
BOOSAPI_AUTH__PROXY_TOKEN: ${PROXY_TOKEN?required}
BOOSAPI_UPSTREAM_BASE: https://api.boos.lat/v1
BOOSAPI_UPSTREAM_KEY: ${UPSTREAM_KEY}
BOOSAPI_SERVER__PORT: "4000"
restart: unless-stopped
EOF
# AUTH_TOKEN = 管理后台登录令牌（管理员只支持 API Token 登录）
# PROXY_TOKEN = 下游客户端调用 /v1/* 的 Token
export AUTH_TOKEN=your-admin-token
export PROXY_TOKEN=sk-your-proxy-token
docker compose up -d
```
启动后访问 `http://localhost:4000/boos`，用 `AUTH_TOKEN` 登录管理员后台；普通用户从用户登录页使用账号密码进入用户工作台。
> [!IMPORTANT]
> 请务必修改 `AUTH_TOKEN` 和 `PROXY_TOKEN`，不要使用默认值。
---
## 📁 项目结构
```
.
├── Cargo.toml # Rust 项目定义
├── config.toml # 默认配置文件
├── Dockerfile # 多阶段构建
├── docker/
│ └── docker-compose.yml
├── src/
│ ├── main.rs # 入口
│ ├── lib.rs # 库入口
│ ├── config.rs # 配置加载（环境变量 + config.toml）
│ ├── error.rs # 统一错误处理
│ ├── db/ # 数据库模型与查询
│ ├── routes/
│ │ ├── mod.rs # 路由组装 + 静态文件 serve
│ │ ├── comfyui_agent.rs # 视频/工作流助手 SSE 聊天
│ │ ├── comfyui/ # 外部 ComfyUI 代理（prompt/history/view）
│ │ ├── proxy/ # OpenAI 兼容代理入口
│ │ ├── auth.rs # 用户注册/登录 JWT
│ │ ├── checkin.rs # 自动签到
│ │ └── ...
│ ├── proxy/ # 代理引擎核心
│ │ ├── conductor/ # Proxy Conductor（故障转移）
│ │ ├── token_router/ # Token 路由引擎
│ │ └── executors/ # 执行器（chat/image/embedding）
│ ├── transformers/ # 协议转换
│ │ ├── openai/ # OpenAI Compatible
│ │ ├── anthropic/ # Claude Messages
│ │ └── gemini/ # Gemini GenerateContent
│ └── services/ # 后台服务
│ ├── cron/ # 定时任务
│ ├── billing/ # 计费逻辑
│ └── notification/ # 通知推送
├── migrations/ # SQLite 迁移
├── src/web/ # 管理台前端源码（React + Vite）
│ ├── authSession.ts # 统一会话工具：commitSession/clearSession/getSessionToken（按 'admin' | 'user' 分桶）
│ ├── loginError.ts # 登录错误归一化（resolveLoginErrorMessage）
│ ├── pages/
│ │ ├── auth/ # 登录页拆分：LoginShell + AdminLoginPage(token-only) + UserLoginPage（OAuthSlot 占位）
│ │ ├── ComfyUIAgent.tsx # 视频/工作流助手聊天界面
│ │ ├── Workflows.tsx # Workflow Studio 入口
│ │ └── ...
│ └── components/
├── website/ # 独立官网（Next.js 16 App Router + React 19）
└── dist/web/ # 前端构建产物（由 Rust serve）
```
## 🔧 环境变量
所有配置通过环境变量覆盖，命名规则：`BOOSAPI_<SECTION>__<KEY>`（双下划线分隔层级）：
```bash
# 服务
BOOSAPI_SERVER__HOST=0.0.0.0
BOOSAPI_SERVER__PORT=4000
BOOSAPI_SERVER__LOG_LEVEL=info
# 认证
BOOSAPI_AUTH__AUTH_TOKEN=your-admin-token
BOOSAPI_AUTH__PROXY_TOKEN=sk-your-proxy-token
BOOSAPI_AUTH__JWT_SECRET=your-jwt-secret
# 数据库（默认 SQLite）
BOOSAPI_DB__URL=sqlite:data/boosapi.db?mode=rwc
# PostgreSQL 准备/迁移
# 当前版本保留 SQLite 作为运行主路径；可先把 SQLite 核心数据迁移到 PostgreSQL。
# 完整 PostgreSQL 业务查询适配需要后续切换运行时 SQL 方言。
# 示例：
# boosapi migrate-sqlite-to-postgres \
# --sqlite-url 'sqlite:data/boosapi.db?mode=rwc' \
# --postgres-url 'postgres://boosapi:password@127.0.0.1:5432/boosapi'
# 目标库已有数据时默认拒绝；确认覆盖时追加 --force-truncate。
# 上游 API（视频/工作流助手回退用，默认本地模式时不需要设置）
# 设置 BOOSAPI_UPSTREAM_BASE 后切换到 fallback-remote 模式；BOOSAPI_UPSTREAM_KEY 缺省时仍用内置 comfyui-agent key
BOOSAPI_UPSTREAM_BASE=https://api.boos.lat/v1
BOOSAPI_UPSTREAM_KEY=sk-your-key
# 前端静态目录（默认 dist/web）
BOOSAPI_WEB_DIR=dist/web
# Workflow 后端
BOOSAPI_COMFYUI__BACKEND=cloud
BOOSAPI_COMFYUI__BASE_URL=https://cloud.comfy.org
BOOSAPI_COMFYUI__API_KEY=your-workflow-backend-key
```
## 🏗️ 技术栈
| 层 | 技术 |
|----|------|
| 后端框架 | **Axum 0.8**（Rust） |
| 运行时 | **Tokio**（异步运行时） |
| 数据库 | **SQLite** 运行主路径 + **PostgreSQL** schema/迁移准备（SQLx） |
| 并行计算 | **Rayon**（CPU 密集任务） |
| 认证鉴权 | **JWT** + API Key 双模式 |
| 代理引擎 | 自定义 Token Router + Proxy Conductor |
| 协议转换 | OpenAI / Claude / Gemini 全兼容 |
| Workflow Studio | 内嵌 ComfyUI 前端 + Cloud / RunningHub / External / BoosAPI 多后端 |
| 视频助手 | SSE 流式 + gpt-image-2 + TTS 自动生成 |
| 管理台前端 | React + Vite（仅构建工具） |
| 独立官网 | Next.js 16 App Router + React 19 + TypeScript |
| 样式 | Tailwind CSS v4 |
| 数据可视化 | VChart |
| 容器化 | Docker + Docker Compose + K3s |
| 构建工具 | Cargo（后端）/ npm（前端静态构建） |
> **运行时零 Node.js 依赖**，Node.js 仅用作前端构建工具。生产环境只需 Rust 编译后的单二进制文件。
> 独立官网位于 `website/`。默认构建会把官网静态导出到 `dist/website/`，Rust 后端会让根路径 `/` 显示官网；管理台仍由 `dist/web/` 提供，管理员入口是 `/boos`，登录后进入 `/dashboard`。
---
## 🛠️ 本地开发
### 后端（Rust）
```bash
# 最快验证：只检查 Rust 后端，不构建前端、不启动服务
./build-and-run.sh --check
# 日常启动：复用前端缓存，后端 dev profile 编译后启动
./build-and-run.sh
# 只重启/编译后端，不碰 Vite/Next
./build-and-run.sh --backend-only
# 接近生产性能但比 release 快
./build-and-run.sh --fast-release
# 完整生产包：构建并嵌入前端/Workflow UI，只输出 boosapi + config.toml
./build-and-run.sh --production
# 运行测试
cargo test
# 环境变量配置
export BOOSAPI_SERVER__HOST=0.0.0.0
export BOOSAPI_SERVER__PORT=4000
export BOOSAPI_AUTH__AUTH_TOKEN=your-admin-token
export BOOSAPI_AUTH__PROXY_TOKEN=sk-your-proxy-token
export BOOSAPI_UPSTREAM_BASE=https://api.boos.lat/v1
export BOOSAPI_UPSTREAM_KEY=sk-your-upstream-key
```
构建加速说明：
- 脚本会在 Linux 下自动使用 `mold` / `lld` 快速链接器；可用 `BOOSAPI_FAST_LINKER=off` 关闭。
- `BOOSAPI_CARGO_JOBS=8 ./build-and-run.sh --check` 可限制 Cargo 并发，避免把开发机打满。
- 生产性能验证优先用 `--fast-release`，真正发布再用 `--production` 或 `--release`。
### 前端（React SPA）
前端使用 Vite 构建，产物由 Rust 后端静态 serve：
```bash
# 安装依赖（首次）
npm install
# 开发模式（热更新，需要 Node.js）
cd src/web && npx vite --host 0.0.0.0
# 类型检查与构建生产版本
npm run typecheck:web
npm run build:web
# 输出到 dist/web/，Rust 后端自动 serve
```
Workflow UI 前端资产单独更新：
```bash
# Comfy Cloud 前端
npm run workflow-ui:install:cloud
# External / RunningHub 前端
npm run workflow-ui:install:external
```
可选使用 Bun 加速主前端构建：
```bash
# 一次性使用 Bun 构建主前端
./build-and-run.sh --bun
# 或设置环境变量，auto 会优先使用可用的 bun，缺省回退 npm/npx
BOOSAPI_FRONTEND_PM=bun ./build-and-run.sh --no-run
BOOSAPI_FRONTEND_PM=auto ./build-and-run.sh
```
> Workflow UI 子模块仍按官方 `pnpm-lock.yaml` 使用 pnpm 构建，避免 ComfyUI 前端依赖兼容问题。
> 生产环境不需要 Node.js 进程。`npm run build` 后，Rust 后端直接 serve 静态文件。
> 前端 API 请求通过 Vite 代理（开发）或同域访问（生产）指向 `localhost:4000`。
### 独立官网（Next.js）
官网已经从管理台中隔离，使用 Next.js 16 App Router、React 19、TypeScript、Tailwind CSS 4 和自定义 SVG/CSS motion system：
```bash
# 首次安装
npm --prefix website install
# 本地开发官网
npm run website:dev
# 类型检查与生产构建
npm run website:typecheck
npm run website:build
```
`./build-and-run.sh` 会同时构建管理台 `dist/web/` 和官网 `dist/website/`。打开主域名 `/` 显示官网；后台路径 `/boos`、`/dashboard`、`/user/*`、`/api/*`、`/v1/*` 等仍由 BoosAPI Rust 服务处理。
### 生产单二进制构建
```bash
./build-and-run.sh --production
```
生产模式会构建主前端与 Workflow UI 资产，并将它们嵌入 Rust 二进制。部署目录通常只需要：
```txt
boosapi
config.toml
```
仓库卫生说明：
- `Cargo.lock` 应随代码提交，保证 Rust 应用在 CI、生产构建和本地排障时依赖版本一致。
- `boosapi.db`、`config.toml` 是本地运行态文件；实际部署时不要提交带真实密钥、Comfy Cloud Key 或生产数据的改动。
- `.agents/`、`.cache/`、`boosapi` / `bossai` 本地二进制、`docker/*.tar` 等构建缓存与大文件已加入忽略规则。
- 旧的 `boosapi-comfyui-multi-tenant-*.tar` 不再作为当前 Workflow 路线的必需产物，生产包应优先使用单二进制 + 配置文件。
### Docker 部署
```bash
# 构建
docker build -t boosapi .
# 运行
docker run -d \
-p 4000:4000 \
-e BOOSAPI_AUTH__AUTH_TOKEN=your-admin-token \
-e BOOSAPI_AUTH__PROXY_TOKEN=sk-your-proxy-token \
-v $(pwd)/data:/app/data \
boosapi
```
### Docker Compose
```yaml
services:
boosapi:
build: .
ports:
- "4000:4000"
volumes:
- ./data:/app/data
environment:
BOOSAPI_AUTH__AUTH_TOKEN: ${AUTH_TOKEN?required}
BOOSAPI_AUTH__PROXY_TOKEN: ${PROXY_TOKEN?required}
BOOSAPI_UPSTREAM_BASE: https://api.boos.lat/v1
BOOSAPI_UPSTREAM_KEY: sk-your-upstream-key
restart: unless-stopped
```
---
## 📜 License
[MIT](LICENSE)
README_EN.md
+196
View File
@@ -0,0 +1,196 @@
<div align="center">
# BoosAPI
**AI Aggregation Gateway + Workflow Studio — one endpoint for many AI relay stations**
<p>
Aggregate New API / One API / OneHub / DoneHub / Veloera / AnyRouter / Sub2API stations
<br>
into <strong>one API key and one compatible endpoint</strong>, with model discovery, smart routing, logs, billing, and failover.
<br>
Workflow Studio embeds the ComfyUI frontend and can run against Comfy Cloud, RunningHub, your own ComfyUI, or BoosAPI's API-native executor.
</p>
<p align="center">
<img alt="Rust" src="https://img.shields.io/badge/Rust-1.85%2B-000000?logo=rust&style=flat">
<img alt="Axum" src="https://img.shields.io/badge/Axum-0.8-3182F6?style=flat">
<img alt="SQLx" src="https://img.shields.io/badge/SQLx-0.8-3E6E93?style=flat">
<img alt="React" src="https://img.shields.io/badge/React-19-61DAFB?logo=react&style=flat">
<img alt="License" src="https://img.shields.io/badge/license-MIT-brightgreen?style=flat">
</p>
<p align="center">
<a href="README.md">中文</a> |
<a href="README_EN.md"><strong>English</strong></a> |
<a href="DEPLOY.md">Deployment</a>
</p>
</div>
---
## Introduction
BoosAPI is a self-hosted Rust gateway for AI relay stations. It centralizes upstream sites, accounts, downstream API keys, model routes, usage logs, image/video generation, user dashboards, and Workflow Studio in one service.
Supported upstreams:
- **Relay panels**: New API, One API, OneHub, DoneHub, Veloera, AnyRouter, Sub2API
- **Compatible APIs**: OpenAI / Claude / Gemini compatible, cliproxyapi / CPA
- **Preset providers**: Aliyun, Zhipu, Doubao Coding Plan, DeepSeek, Moonshot, MiniMax, ModelScope
- **OAuth connections**: Codex, Claude, Gemini CLI, Antigravity
## Key Features
### Unified API Gateway
- OpenAI-compatible `/v1/chat/completions`, `/v1/responses`, `/v1/images/generations`, `/v1/models`, and files endpoints
- Claude-compatible `/v1/messages`, including request/response and streaming event conversion
- Smart token routing, channel cooldown, failover, model discovery, and usage accounting
- Admin and user dashboards with API key management and model visibility controls
### Workflow Studio
Workflow Studio uses an embedded ComfyUI frontend. The execution backend is selected by `comfyui.backend`:
| backend | Purpose |
|---------|---------|
| `cloud` | Proxy Comfy Cloud API for cloud execution and subscription models |
| `runninghub` | Proxy RunningHub's ComfyUI-compatible API for its plugins, models, and workflows |
| `external` | Proxy a full ComfyUI instance you deploy yourself |
| `boosapi` | Use BoosAPI's Rust API-native workflow executor and configured model routes |
| `docker` | Local full ComfyUI mode for GPU machines and local model directories |
Cloud, RunningHub, external API, and BoosAPI executor modes do not require a GPU on the BoosAPI server. A GPU is only needed when you run local ComfyUI inference on the same machine.
### Assistants
- Video / workflow assistant with Markdown chat, reasoning sections, attachments, and model route selection
- Picture assistant using `/v1/images/generations`, background tasks, progress display, cancellation, and Workspace archive
- Volcengine video task templates for create-task and query-task flows
## Hardware Guide
| Mode | CPU | Memory | Disk | GPU |
|------|-----|--------|------|-----|
| Gateway, admin UI, `/v1/*` proxy only | 2 cores minimum, 4 recommended | 2GB minimum, 4GB recommended | 10GB+ | Not required |
| BoosAPI + Workflow UI + remote APIs / Comfy Cloud / RunningHub | 4 cores recommended | 4GB minimum, 8GB recommended | 20-50GB | Not required |
| External ComfyUI proxy | 4 cores recommended | 8GB recommended | 50GB+ | Not on BoosAPI; required by the ComfyUI machine as needed |
| Local Docker / local ComfyUI image generation | 4-8 cores | 16GB+ | 100GB+ | NVIDIA 8GB VRAM minimum, 12GB+ recommended |
| Local video / digital human / large workflows | 8 cores+ | 32GB minimum, 64GB recommended | 200GB-1TB | NVIDIA 24GB VRAM minimum, 48GB+ recommended |
Recommended SaaS gateway server:
```txt
4 CPU cores
8GB RAM
50GB SSD
No GPU required
```
## Quick Start
```bash
cp config.toml.example config.toml
./build-and-run.sh
```
For a production bundle with embedded web assets:
```bash
./build-and-run.sh --production
```
The production output is intended to run with only:
```txt
boosapi
config.toml
```
Web assets and Workflow UI assets are embedded in the Rust binary when built for production.
## Workflow Backend Configuration
Comfy Cloud:
```toml
[comfyui]
backend = "cloud"
base_url = "https://cloud.comfy.org"
api_key = "your-comfy-cloud-api-key"
```
RunningHub:
```toml
[comfyui]
backend = "runninghub"
base_url = "https://www.runninghub.cn/your-comfy-compatible-endpoint"
api_key = "your-runninghub-api-key"
```
External ComfyUI:
```toml
[comfyui]
backend = "external"
base_url = "http://127.0.0.1:8188"
```
BoosAPI API-native executor:
```toml
[comfyui]
backend = "boosapi"
```
## Environment Variables
Configuration can be overridden with `BOOSAPI_<SECTION>__<KEY>`:
```bash
BOOSAPI_SERVER__HOST=0.0.0.0
BOOSAPI_SERVER__PORT=4000
BOOSAPI_AUTH__AUTH_TOKEN=your-admin-token
BOOSAPI_AUTH__PROXY_TOKEN=sk-your-proxy-token
BOOSAPI_AUTH__JWT_SECRET=your-jwt-secret
BOOSAPI_DB__URL=sqlite:data/boosapi.db?mode=rwc
```
## Tech Stack
| Layer | Tech |
|-------|------|
| Backend | Rust, Axum 0.8, Tokio |
| Database | SQLx, SQLite runtime path, PostgreSQL schema/migration preparation |
| Proxy engine | Token Router + Proxy Conductor |
| Protocols | OpenAI / Claude / Gemini compatible transformers |
| Frontend | React 19 + Vite |
| Workflow UI | Embedded ComfyUI frontend variants for cloud/external-compatible backends |
| Static serving | Rust binary serves `dist/web` and Workflow UI assets |
| Container | Docker / Docker Compose |
Node.js is only a build-time tool for the frontend. Production does not require a Node.js process.
## Local Development
```bash
cargo check
cargo run
pnpm install
pnpm run dev:web
```
Build checks:
```bash
cargo check
pnpm run typecheck:web
npx vite build
```
## License
[MIT](LICENSE)
assets/picture-agent/linux_do_2036927_prompts_images.with_tags.json
+12837
View File
File diff suppressed because one or more lines are too long
boosapi.db
BIN
View File
Binary file not shown.
build-and-run.sh
Executable
+662
View File
@@ -0,0 +1,662 @@
#!/usr/bin/env bash
# 编译前后端并启动服务
set -euo pipefail
ROOT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
cd "$ROOT_DIR"
# ── 工具函数 ──────────────────────────────────────────────────────────────────
log() { echo "[$(date '+%H:%M:%S')] $*"; }
ok() { echo "[$(date '+%H:%M:%S')] ✓ $*"; }
fail() { echo "[$(date '+%H:%M:%S')] ✗ $*" >&2; exit 1; }
# ── 参数 ──────────────────────────────────────────────────────────────────────
BUILD_PROFILE="${BOOSAPI_BUILD_PROFILE:-dev}"
FRONTEND_ONLY=0
BACKEND_ONLY=0
CHECK_ONLY=0
NO_RUN=0
FORCE_FRONTEND=0
SKIP_FRONTEND=0
PRODUCTION_BUNDLE=0
PRODUCTION_DIR="${BOOSAPI_PRODUCTION_DIR:-$ROOT_DIR/dist/production}"
CARGO_FEATURES="${BOOSAPI_CARGO_FEATURES:-}"
CARGO_JOBS="${BOOSAPI_CARGO_JOBS:-}"
FAST_LINKER="${BOOSAPI_FAST_LINKER:-auto}"
FRONTEND_PM="${BOOSAPI_FRONTEND_PM:-auto}"
BUILD_TIMINGS=()
usage() {
cat <<'EOF'
用法: ./build-and-run.sh [选项]
选项:
--dev 使用 dev 模式编译后端（默认，最快）
--release 使用 release 模式编译后端（更慢但性能好）
--fast-release 使用 fast-release 模式编译后端（比 release 快，性能接近生产）
--profile <name> 指定构建 profile：dev / release / fast-release
--production 生产编译：先构建前端并嵌入二进制，再输出 dist/production/{boosapi,config.toml}
--prod 同 --production
--production-dir <dir>
指定生产产物目录（默认：dist/production）
--check 只执行 cargo check，不构建前端、不启动服务（最快验证）
--backend-check 同 --check
--frontend-only 只构建前端
--backend-only 只构建后端
--force-frontend 强制重建前端，忽略缓存
--skip-frontend 跳过前端构建（沿用现有 dist/web）
--bun 主前端使用 Bun 执行 Vite 构建（Workflow UI 子模块会自动准备 pnpm）
--no-run 构建后不启动服务
BOOSAPI_BUILD_PROFILE 可设置默认 profile（dev / release / fast-release）
BOOSAPI_CARGO_FEATURES 可覆盖后端 Cargo features（默认：空）
BOOSAPI_CARGO_JOBS 可设置 cargo 并发任务数，例如 8
BOOSAPI_FAST_LINKER 可设置 auto / off / mold / lld（默认：auto，Linux 下优先 mold）
BOOSAPI_FRONTEND_PM 可设置主前端构建器：auto / npm / bun（默认：auto）
BOOSAPI_PRODUCTION_DIR 可设置 --production 默认产物目录
-h, --help 显示帮助
示例:
./build-and-run.sh --release
./build-and-run.sh --fast-release
./build-and-run.sh --check
./build-and-run.sh --bun
./build-and-run.sh --production
./build-and-run.sh --production --production-dir /opt/boosapi-release
BOOSAPI_BUILD_PROFILE=release ./build-and-run.sh
EOF
}
while [ $# -gt 0 ]; do
case "$1" in
--dev) BUILD_PROFILE="dev" ;;
--release) BUILD_PROFILE="release" ;;
--fast-release) BUILD_PROFILE="fast-release" ;;
--production|--prod)
PRODUCTION_BUNDLE=1
BUILD_PROFILE="release"
NO_RUN=1
;;
--production-dir)
shift
[ $# -gt 0 ] || fail "--production-dir 需要目录参数"
PRODUCTION_DIR="$1"
;;
--check|--backend-check)
CHECK_ONLY=1
BACKEND_ONLY=1
NO_RUN=1
;;
--profile)
shift
[ $# -gt 0 ] || fail "--profile 需要参数：dev / release / fast-release"
BUILD_PROFILE="$1"
;;
--frontend-only) FRONTEND_ONLY=1 ;;
--backend-only) BACKEND_ONLY=1 ;;
--force-frontend) FORCE_FRONTEND=1 ;;
--skip-frontend) SKIP_FRONTEND=1 ;;
--bun) FRONTEND_PM="bun" ;;
--no-run) NO_RUN=1 ;;
--rebuild-image) log "--rebuild-image 已废弃：内置 Docker ComfyUI 工作台已移除，忽略该参数" ;;
-h|--help) usage; exit 0 ;;
*) echo "未知参数: $1" >&2; usage >&2; exit 1 ;;
esac
shift
done
if [ "$FRONTEND_ONLY" -eq 1 ] && [ "$BACKEND_ONLY" -eq 1 ]; then
fail "--frontend-only 和 --backend-only 不能同时使用"
fi
if [ "$PRODUCTION_BUNDLE" -eq 1 ] && [ "$FRONTEND_ONLY" -eq 1 ]; then
fail "--production 不能和 --frontend-only 同时使用"
fi
if [ "$PRODUCTION_BUNDLE" -eq 1 ] && [ "$BACKEND_ONLY" -eq 1 ]; then
fail "--production 需要先构建前端以嵌入 web，不能和 --backend-only 同时使用"
fi
if [ "$PRODUCTION_BUNDLE" -eq 1 ] && [ "$CHECK_ONLY" -eq 1 ]; then
fail "--production 不能和 --check 同时使用"
fi
case "$BUILD_PROFILE" in
dev|debug) BUILD_PROFILE="dev" ;;
release|fast-release) ;;
*) fail "未知构建 profile: $BUILD_PROFILE（可选：dev / release / fast-release）" ;;
esac
case "$FAST_LINKER" in
auto|off|none|mold|lld) ;;
*) fail "未知 BOOSAPI_FAST_LINKER: $FAST_LINKER（可选：auto / off / mold / lld）" ;;
esac
timer_start() {
date +%s
}
record_timing() {
local label="$1"
local started="$2"
local ended
ended="$(date +%s)"
BUILD_TIMINGS+=("${label}: $((ended - started))s")
}
print_timing_summary() {
[ "${#BUILD_TIMINGS[@]}" -gt 0 ] || return 0
log "构建耗时:"
local item
for item in "${BUILD_TIMINGS[@]}"; do
log " - $item"
done
}
append_rustflags() {
local flags="$1"
if [[ " ${RUSTFLAGS:-} " != *" $flags "* ]]; then
export RUSTFLAGS="${RUSTFLAGS:+$RUSTFLAGS }$flags"
fi
}
build_cargo_args() {
CARGO_BASE_ARGS=()
CARGO_FEATURE_ARGS=()
if [ -n "$CARGO_JOBS" ]; then
CARGO_BASE_ARGS+=(--jobs "$CARGO_JOBS")
fi
if [ -n "$CARGO_FEATURES" ]; then
CARGO_FEATURE_ARGS=(--features "$CARGO_FEATURES")
fi
}
configure_fast_linker() {
local mode="$FAST_LINKER"
case "$(uname -s 2>/dev/null || true)" in
Linux) ;;
*)
[ "$mode" = "auto" ] && return 0
fail "BOOSAPI_FAST_LINKER=$mode 目前只在 Linux 构建环境自动配置"
;;
esac
if [ "$mode" = "off" ] || [ "$mode" = "none" ]; then
return 0
fi
if [ "$mode" = "auto" ]; then
if command -v mold >/dev/null 2>&1; then
mode="mold"
elif command -v ld.lld >/dev/null 2>&1 || command -v lld >/dev/null 2>&1; then
mode="lld"
else
log "提示: 安装 mold 或 lld 可显著缩短 Rust 链接时间；当前使用系统默认链接器"
return 0
fi
fi
case "$mode" in
mold)
command -v mold >/dev/null 2>&1 || fail "BOOSAPI_FAST_LINKER=mold 但未找到 mold"
if command -v clang >/dev/null 2>&1; then
append_rustflags "-C linker=clang"
elif ! command -v gcc >/dev/null 2>&1 && [ -z "${RUSTC_LINKER:-}" ]; then
fail "启用 mold 需要 clang 或 gcc 作为 linker driver"
fi
append_rustflags "-C link-arg=-fuse-ld=mold"
log "Rust 快速链接器: mold（BOOSAPI_FAST_LINKER=$FAST_LINKER）"
;;
lld)
if ! command -v ld.lld >/dev/null 2>&1 && ! command -v lld >/dev/null 2>&1; then
fail "BOOSAPI_FAST_LINKER=lld 但未找到 ld.lld/lld"
fi
if command -v clang >/dev/null 2>&1; then
append_rustflags "-C linker=clang"
elif ! command -v gcc >/dev/null 2>&1 && [ -z "${RUSTC_LINKER:-}" ]; then
fail "启用 lld 需要 clang 或 gcc 作为 linker driver"
fi
append_rustflags "-C link-arg=-fuse-ld=lld"
log "Rust 快速链接器: lld（BOOSAPI_FAST_LINKER=$FAST_LINKER）"
;;
esac
}
# Enable sccache as the rustc wrapper when available. sccache caches compiled
# crates keyed by source + flags, so dependency rebuilds / clean builds / branch
# switches reuse prior output. It transparently skips incremental crates, so the
# dev profile still relies mainly on incremental; release/fast-release benefit
# most. Set BOOSAPI_SCCACHE=off to disable.
configure_sccache() {
case "${BOOSAPI_SCCACHE:-auto}" in
off|none|0) return 0 ;;
esac
if [ -n "${RUSTC_WRAPPER:-}" ]; then
return 0 # respect an externally configured wrapper
fi
if command -v sccache >/dev/null 2>&1; then
export RUSTC_WRAPPER="sccache"
log "Rust 编译缓存: sccache（BOOSAPI_SCCACHE=off 可关闭）"
fi
}
server_port() {
if [ -n "${BOOSAPI_SERVER__PORT:-}" ]; then
printf '%s\n' "$BOOSAPI_SERVER__PORT"
return
fi
awk '
/^\[server\]/ { in_server = 1; next }
/^\[/ { in_server = 0 }
in_server && /^[[:space:]]*port[[:space:]]*=/ {
gsub(/[^0-9]/, "", $0)
print $0
exit
}
' "$ROOT_DIR/config.toml" 2>/dev/null || true
}
is_running_pid() {
local pid="$1"
[ -n "$pid" ] && kill -0 "$pid" 2>/dev/null
}
stop_pids() {
local label="$1"
shift || true
local pids=()
local pid
for pid in "$@"; do
if [ -n "$pid" ] && [ "$pid" != "$$" ] && is_running_pid "$pid"; then
pids+=("$pid")
fi
done
if [ "${#pids[@]}" -eq 0 ]; then
return 0
fi
log "停止旧进程 ${label}: ${pids[*]}"
kill -TERM "${pids[@]}" 2>/dev/null || true
for _ in 1 2 3 4 5; do
local alive=()
for pid in "${pids[@]}"; do
if is_running_pid "$pid"; then
alive+=("$pid")
fi
done
if [ "${#alive[@]}" -eq 0 ]; then
ok "旧进程已停止"
return 0
fi
sleep 1
pids=("${alive[@]}")
done
log "旧进程未及时退出，强制结束: ${pids[*]}"
kill -KILL "${pids[@]}" 2>/dev/null || true
}
stop_previous_server() {
local binary_pids=()
local port_pids=()
local port
while IFS= read -r pid; do
[ -n "$pid" ] && binary_pids+=("$pid")
done < <(pgrep -f "target/(debug|release|fast-release)/boosapi" 2>/dev/null || true)
stop_pids "boosapi binary" "${binary_pids[@]}"
port="$(server_port)"
port="${port:-4000}"
if command -v fuser >/dev/null 2>&1; then
while IFS= read -r pid; do
[ -n "$pid" ] && port_pids+=("$pid")
done < <(fuser "${port}/tcp" 2>/dev/null | tr ' ' '\n' || true)
stop_pids "占用 ${port}/tcp" "${port_pids[@]}"
else
log "未找到 fuser，跳过端口 ${port}/tcp 占用检查"
fi
}
ensure_pnpm() {
if command -v pnpm >/dev/null 2>&1; then
return 0
fi
command -v corepack >/dev/null 2>&1 || fail "未找到 pnpm/corepack，无法自动准备 pnpm。请安装 Node.js 22+ 或 pnpm"
log "未找到 pnpm，尝试通过 corepack 自动启用..."
corepack enable
corepack prepare pnpm@latest --activate
command -v pnpm >/dev/null 2>&1 || fail "pnpm 自动准备失败，请手动安装 pnpm"
}
install_frontend_dependencies() {
local frontend_pm="$1"
if [ "$frontend_pm" = "bun" ]; then
command -v bun >/dev/null 2>&1 || fail "未找到 bun，请安装 Bun 或移除 --bun"
if [ ! -d "$ROOT_DIR/node_modules" ] || [ "$FORCE_FRONTEND" -eq 1 ]; then
log "安装主前端依赖 (bun install)..."
bun install
fi
return 0
fi
command -v node >/dev/null 2>&1 || fail "未找到 node，请先安装 Node.js"
ensure_pnpm
if [ ! -d "$ROOT_DIR/node_modules" ] || [ "$FORCE_FRONTEND" -eq 1 ]; then
log "安装主前端依赖 (pnpm install)..."
pnpm install --frozen-lockfile
fi
}
build_frontend() {
local started
started="$(timer_start)"
if [ "$SKIP_FRONTEND" -eq 1 ]; then
log "跳过前端构建（--skip-frontend）"
record_timing "前端检查" "$started"
return 0
fi
local frontend_pm="$FRONTEND_PM"
case "$frontend_pm" in
auto)
if command -v bun >/dev/null 2>&1; then
frontend_pm="bun"
else
frontend_pm="npm"
fi
;;
npm|bun) ;;
*) fail "未知 BOOSAPI_FRONTEND_PM: $frontend_pm（可选：auto / npm / bun）" ;;
esac
install_frontend_dependencies "$frontend_pm"
local fingerprint_file="$ROOT_DIR/dist/web/.boosapi-build-fingerprint"
local fingerprint
fingerprint="$(
{
printf 'build-script-v2\n'
printf 'frontend_pm=%s\n' "$frontend_pm"
printf 'node='
node --version 2>/dev/null || true
printf 'npx='
npx --version 2>/dev/null || true
printf 'bun='
bun --version 2>/dev/null || true
for path in package.json pnpm-lock.yaml package-lock.json yarn.lock vite.config.ts tsconfig.json tsconfig.web.json tsconfig.transpile.json src/web src/shared; do
[ -e "$ROOT_DIR/$path" ] && find "$ROOT_DIR/$path" -type f -print
done | sort | xargs -r sha256sum
} | sha256sum | awk '{print $1}'
)"
if [ "$FORCE_FRONTEND" -eq 0 ] \
&& [ -f "$fingerprint_file" ] \
&& [ -f "$ROOT_DIR/dist/web/index.html" ] \
&& [ "$(cat "$fingerprint_file" 2>/dev/null || true)" = "$fingerprint" ]; then
ok "前端无变化，跳过 Vite 构建 → dist/web/"
record_timing "前端检查" "$started"
return 0
fi
log "构建前端 (Vite via ${frontend_pm})..."
# 直接调用 vite build；桌面端构建链路已移除。
if [ "$frontend_pm" = "bun" ]; then
bunx --bun vite build
else
pnpm exec vite build
fi
mkdir -p "$ROOT_DIR/dist/web"
printf '%s\n' "$fingerprint" > "$fingerprint_file"
ok "前端构建完成 → dist/web/"
record_timing "前端构建" "$started"
}
install_website_dependencies() {
command -v node >/dev/null 2>&1 || fail "未找到 node，请先安装 Node.js"
if [ ! -d "$ROOT_DIR/website/node_modules" ] || [ "$FORCE_FRONTEND" -eq 1 ]; then
log "安装官网依赖 (npm --prefix website install)..."
npm --prefix "$ROOT_DIR/website" install
fi
}
build_public_website() {
local started
started="$(timer_start)"
if [ "$SKIP_FRONTEND" -eq 1 ]; then
log "跳过官网构建（--skip-frontend）"
record_timing "官网检查" "$started"
return 0
fi
[ -f "$ROOT_DIR/website/package.json" ] || fail "未找到 website/package.json，无法构建官网"
install_website_dependencies
local fingerprint_file="$ROOT_DIR/dist/website/.bossai-website-build-fingerprint"
local fingerprint
fingerprint="$(
{
printf 'website-build-v1\n'
printf 'node='
node --version 2>/dev/null || true
printf 'npm='
npm --version 2>/dev/null || true
for path in website/package.json website/package-lock.json website/next.config.ts website/postcss.config.mjs website/tsconfig.json website/app website/public; do
[ -e "$ROOT_DIR/$path" ] && find "$ROOT_DIR/$path" -type f -print
done | sort | xargs -r sha256sum
} | sha256sum | awk '{print $1}'
)"
if [ "$FORCE_FRONTEND" -eq 0 ] \
&& [ -f "$fingerprint_file" ] \
&& [ -f "$ROOT_DIR/dist/website/index.html" ] \
&& [ "$(cat "$fingerprint_file" 2>/dev/null || true)" = "$fingerprint" ]; then
ok "官网无变化，跳过 Next 构建 → dist/website/"
record_timing "官网检查" "$started"
return 0
fi
log "构建官网 (Next.js static export)..."
npm --prefix "$ROOT_DIR/website" run build
rm -rf "$ROOT_DIR/dist/website"
mkdir -p "$ROOT_DIR/dist/website"
cp -R "$ROOT_DIR/website/out/." "$ROOT_DIR/dist/website/"
printf '%s\n' "$fingerprint" > "$fingerprint_file"
ok "官网构建完成 → dist/website/"
record_timing "官网构建" "$started"
}
ensure_workflow_ui_for_embedding() {
local started
started="$(timer_start)"
if [ "$SKIP_FRONTEND" -eq 1 ]; then
log "跳过 Workflow UI 构建检查（--skip-frontend）"
record_timing "Workflow UI 检查" "$started"
return 0
fi
if [ -f "$ROOT_DIR/dist/workflow-ui-external/index.html" ] \
&& [ -f "$ROOT_DIR/dist/workflow-ui-cloud/index.html" ] \
&& [ -f "$ROOT_DIR/dist/workflow-ui/index.html" ] \
&& [ "$FORCE_FRONTEND" -eq 0 ]; then
ok "Workflow UI 已存在，跳过构建 → dist/workflow-ui-{external,cloud}/"
record_timing "Workflow UI 检查" "$started"
return 0
fi
command -v git >/dev/null 2>&1 || fail "未找到 git，无法构建 Workflow UI"
command -v node >/dev/null 2>&1 || fail "未找到 node，无法构建 Workflow UI"
ensure_pnpm
log "构建 Workflow UI 双前端（external + cloud，用于嵌入二进制）..."
pnpm run workflow-ui:install
ok "Workflow UI 构建完成 → dist/workflow-ui-external/ dist/workflow-ui-cloud/"
record_timing "Workflow UI 构建" "$started"
}
build_backend() {
local started
started="$(timer_start)"
if ! command -v cargo >/dev/null 2>&1; then
fail "未找到 cargo，请先安装 Rust 工具链"
fi
configure_fast_linker
configure_sccache
build_cargo_args
if [ "$CHECK_ONLY" -eq 1 ]; then
if [ "$BUILD_PROFILE" = "release" ]; then
log "检查后端 (cargo check --release ${CARGO_BASE_ARGS[*]} ${CARGO_FEATURE_ARGS[*]})..."
cargo check "${CARGO_BASE_ARGS[@]}" --release "${CARGO_FEATURE_ARGS[@]}"
elif [ "$BUILD_PROFILE" = "fast-release" ]; then
log "检查后端 (cargo check --profile fast-release ${CARGO_BASE_ARGS[*]} ${CARGO_FEATURE_ARGS[*]})..."
cargo check "${CARGO_BASE_ARGS[@]}" --profile fast-release "${CARGO_FEATURE_ARGS[@]}"
else
log "检查后端 (cargo check ${CARGO_BASE_ARGS[*]} ${CARGO_FEATURE_ARGS[*]})..."
cargo check "${CARGO_BASE_ARGS[@]}" "${CARGO_FEATURE_ARGS[@]}"
fi
ok "后端检查完成"
record_timing "后端检查" "$started"
return 0
fi
if [ "$BUILD_PROFILE" = "release" ]; then
log "构建后端 (cargo build --release ${CARGO_BASE_ARGS[*]} ${CARGO_FEATURE_ARGS[*]})..."
cargo build "${CARGO_BASE_ARGS[@]}" --release "${CARGO_FEATURE_ARGS[@]}"
BINARY="$ROOT_DIR/target/release/boosapi"
ok "后端构建完成 → target/release/boosapi"
elif [ "$BUILD_PROFILE" = "fast-release" ]; then
log "构建后端 (cargo build --profile fast-release ${CARGO_BASE_ARGS[*]} ${CARGO_FEATURE_ARGS[*]})..."
cargo build "${CARGO_BASE_ARGS[@]}" --profile fast-release "${CARGO_FEATURE_ARGS[@]}"
BINARY="$ROOT_DIR/target/fast-release/boosapi"
ok "后端构建完成 → target/fast-release/boosapi"
else
log "构建后端 (cargo build ${CARGO_BASE_ARGS[*]} ${CARGO_FEATURE_ARGS[*]})..."
cargo build "${CARGO_BASE_ARGS[@]}" "${CARGO_FEATURE_ARGS[@]}"
BINARY="$ROOT_DIR/target/debug/boosapi"
ok "后端构建完成 → target/debug/boosapi"
fi
record_timing "后端构建" "$started"
}
build_production_bundle() {
local started
started="$(timer_start)"
[ -n "${BINARY:-}" ] || fail "生产打包失败：后端二进制路径为空"
[ -f "$BINARY" ] || fail "生产打包失败：未找到二进制 $BINARY"
[ -f "$ROOT_DIR/config.toml" ] || fail "生产打包失败：未找到 config.toml"
rm -rf "$PRODUCTION_DIR"
mkdir -p "$PRODUCTION_DIR"
cp "$BINARY" "$PRODUCTION_DIR/boosapi"
cp "$ROOT_DIR/config.toml" "$PRODUCTION_DIR/config.toml"
chmod +x "$PRODUCTION_DIR/boosapi"
if command -v strip >/dev/null 2>&1; then
log "压缩生产二进制符号表 (strip)..."
strip "$PRODUCTION_DIR/boosapi" 2>/dev/null || log "strip 失败，保留未压缩二进制"
fi
ok "生产产物已生成 → $PRODUCTION_DIR"
log "产物内容:"
(cd "$PRODUCTION_DIR" && ls -lh boosapi config.toml)
log "部署时只需要复制该目录内的 boosapi 和 config.toml；主 Web 前端已嵌入二进制。"
record_timing "生产打包" "$started"
}
cleanup_started_server() {
if [ -n "${STARTED_PID:-}" ] && is_running_pid "$STARTED_PID"; then
log "停止本次启动的后端进程: $STARTED_PID"
kill -TERM "$STARTED_PID" 2>/dev/null || true
wait "$STARTED_PID" 2>/dev/null || true
fi
}
# ── 构建 / 启动 ────────────────────────────────────────────────────────────────
if [ "$FRONTEND_ONLY" -eq 1 ]; then
build_frontend
build_public_website
print_timing_summary
log "跳过启动（--frontend-only）"
exit 0
fi
if [ "$BACKEND_ONLY" -ne 1 ]; then
if [ "$PRODUCTION_BUNDLE" -eq 1 ]; then
# Production embeds frontend assets into the binary; keep the ordering
# explicit (frontend → workflow UI → backend) to avoid a race on the
# embedded files. No parallelism here.
build_frontend
build_public_website
ensure_workflow_ui_for_embedding
build_backend
else
# Dev / normal builds: frontend (vite) + website (next) run in the
# background while the backend (cargo) builds in the foreground. The
# backend stays in the main shell so it can still set BINARY and other
# globals the launch step depends on. Total time ≈ max(frontend, backend).
log "并行构建：前端/官网（后台）+ 后端（前台）..."
( build_frontend && build_public_website ) &
fe_pid=$!
be_status=0
build_backend || be_status=$?
fe_status=0
wait "$fe_pid" || fe_status=$?
[ "$be_status" -eq 0 ] || fail "后端构建失败（exit $be_status）"
[ "$fe_status" -eq 0 ] || fail "前端/官网构建失败（exit $fe_status）"
fi
else
build_backend
fi
if [ "$CHECK_ONLY" -eq 1 ]; then
print_timing_summary
log "跳过启动（--check）"
exit 0
fi
if [ "$PRODUCTION_BUNDLE" -eq 1 ]; then
build_production_bundle
print_timing_summary
exit 0
fi
if [ "$NO_RUN" -eq 1 ]; then
print_timing_summary
log "跳过启动（--no-run）"
exit 0
fi
print_timing_summary
stop_previous_server
log "启动服务..."
if [ "$BACKEND_ONLY" -eq 1 ]; then
exec "$BINARY"
fi
"$BINARY" &
STARTED_PID=$!
trap cleanup_started_server INT TERM EXIT
ok "后端已启动，PID: $STARTED_PID"
ok "前后端已就绪（profile: $BUILD_PROFILE），按 Ctrl+C 停止服务"
wait "$STARTED_PID"
comfy/boosapi_comfy_nodes.py
+304
View File
@@ -0,0 +1,304 @@
"""
BoosAPI ComfyUI Custom Nodes
让 ComfyUI workflow 调用 BoosAPI 的 AI 模型（图像生成、LLM 等）。
配置：通过环境变量设置 BoosAPI 地址，或使用默认 http://127.0.0.1:4000/v1
环境变量：
BOOSAPI_BASE — BoosAPI 地址（默认 http://127.0.0.1:4000）
BOOSAPI_KEY — API Key（默认 sk-boos4721）
"""
import json
import os
import requests
# ── Config ───────────────────────────────────────────────────────────────
BOOSAPI_BASE_RAW = os.environ.get("BOOSAPI_BASE", "http://127.0.0.1:4000")
BOOSAPI_KEY = os.environ.get("BOOSAPI_KEY", "sk-boos4721")
HEADERS = {
"Authorization": f"Bearer {BOOSAPI_KEY}",
"Content-Type": "application/json",
}
FALLBACK_CHAT_MODELS = ["gpt-5.5", "gpt-5.4", "gpt-5.4-mini", "gpt-5.3-codex", "gpt-5.2"]
FALLBACK_IMAGE_MODELS = ["gpt-image-2", "gpt-image-1", "dall-e-3", "dall-e-2"]
FALLBACK_ALL_MODELS = FALLBACK_IMAGE_MODELS + FALLBACK_CHAT_MODELS
def normalize_boosapi_root(base):
base = str(base or "http://127.0.0.1:4000").strip().rstrip("/")
if base.endswith("/v1"):
base = base[:-3].rstrip("/")
return base or "http://127.0.0.1:4000"
BOOSAPI_ROOT = normalize_boosapi_root(BOOSAPI_BASE_RAW)
BOOSAPI_V1 = f"{BOOSAPI_ROOT}/v1"
def raise_for_status_with_body(resp):
try:
resp.raise_for_status()
except requests.HTTPError as e:
body = (resp.text or "").strip()
if body:
print(f"[BoosAPI] HTTP {resp.status_code} response: {body[:2000]}")
raise requests.HTTPError(f"{e}; response body: {body[:1000]}", response=resp)
raise
def _ordered_unique(values):
seen = set()
result = []
for value in values:
value = str(value or "").strip()
if not value or value in seen:
continue
seen.add(value)
result.append(value)
return result
def fetch_boosapi_models():
"""Fetch models exposed by BoosAPI's own /v1/models route."""
try:
resp = requests.get(f"{BOOSAPI_V1}/models", headers=HEADERS, timeout=8)
resp.raise_for_status()
data = resp.json()
models = []
for item in data.get("data", []):
if isinstance(item, dict):
models.append(item.get("id") or item.get("name"))
elif isinstance(item, str):
models.append(item)
return _ordered_unique(models)
except Exception as e:
print(f"[BoosAPI] model list fallback: {e}")
return None
def model_choices(kind="all"):
models = fetch_boosapi_models()
if models is None:
if kind == "image":
return FALLBACK_IMAGE_MODELS
if kind == "chat":
return FALLBACK_CHAT_MODELS
return FALLBACK_ALL_MODELS
if kind == "image":
image_like = [
model for model in models
if any(token in model.lower() for token in ("image", "dall", "flux", "sd", "midjourney"))
]
return _ordered_unique(image_like + models) or FALLBACK_IMAGE_MODELS
if kind == "chat":
chat_like = [
model for model in models
if not any(token in model.lower() for token in ("image", "dall", "flux", "sd", "midjourney"))
]
return _ordered_unique(chat_like + models) or FALLBACK_CHAT_MODELS
return _ordered_unique(models) or FALLBACK_ALL_MODELS
def default_model(kind="all"):
choices = model_choices(kind)
return choices[0] if choices else FALLBACK_ALL_MODELS[0]
# ── Node Mappings ────────────────────────────────────────────────────────
NODE_CLASS_MAPPINGS = {}
NODE_DISPLAY_NAME_MAPPINGS = {}
# ═════════════════════════════════════════════════════════════════════════
# Node: BoosAPIImageGen — 图像生成 (OpenAI DALL-E / 兼容格式)
# ═════════════════════════════════════════════════════════════════════════
class BoosAPIImageGen:
"""调用 BoosAPI /v1/images/generations 生成图像"""
@classmethod
def INPUT_TYPES(cls):
return {
"required": {
"prompt": ("STRING", {"multiline": True, "default": ""}),
"model": (model_choices("image"), {"default": default_model("image")}),
"size": (["1024x1024", "1792x1024", "1024x1792"], {"default": "1024x1024"}),
"quality": (["standard", "hd"], {"default": "standard"}),
"n": ("INT", {"default": 1, "min": 1, "max": 4}),
},
"optional": {
"style": (["vivid", "natural"], {"default": "vivid"}),
},
}
RETURN_TYPES = ("IMAGE", "STRING")
RETURN_NAMES = ("image", "metadata")
FUNCTION = "generate"
OUTPUT_NODE = True
CATEGORY = "BoosAPI"
def generate(self, prompt, model, size, quality, n, style="vivid"):
url = f"{BOOSAPI_V1}/images/generations"
payload = {
"model": model,
"prompt": prompt,
"n": n,
"size": size,
"quality": quality,
"style": style,
"response_format": "b64_json",
}
try:
resp = requests.post(url, headers=HEADERS, json=payload, timeout=120)
raise_for_status_with_body(resp)
data = resp.json()
images = data.get("data", [])
# Return first image as b64
from io import BytesIO
import base64
import torch
from PIL import Image
b64_data = images[0]["b64_json"]
img_bytes = base64.b64decode(b64_data)
pil_img = Image.open(BytesIO(img_bytes)).convert("RGB")
img_tensor = torch.from_numpy(
__import__("numpy").array(pil_img).astype("float32") / 255.0
).unsqueeze(0)
metadata = json.dumps({
"model": model,
"size": size,
"revised_prompt": data.get("data", [{}])[0].get("revised_prompt", ""),
})
return (img_tensor, metadata)
except Exception as e:
print(f"[BoosAPI] ImageGen failed: {e}")
raise
# ═════════════════════════════════════════════════════════════════════════
# Node: BoosAPILLM — LLM Chat (流式文本生成)
# ═════════════════════════════════════════════════════════════════════════
class BoosAPILLM:
"""调用 BoosAPI /v1/chat/completions 生成文本"""
@classmethod
def INPUT_TYPES(cls):
return {
"required": {
"prompt": ("STRING", {"multiline": True, "default": ""}),
"model": (model_choices("chat"), {"default": default_model("chat")}),
"system_prompt": ("STRING", {"multiline": True, "default": ""}),
"temperature": ("FLOAT", {"default": 0.7, "min": 0.0, "max": 2.0}),
"max_tokens": ("INT", {"default": 2048, "min": 1, "max": 16384}),
},
}
RETURN_TYPES = ("STRING",)
RETURN_NAMES = ("text",)
FUNCTION = "chat"
OUTPUT_NODE = True
CATEGORY = "BoosAPI"
def chat(self, prompt, model, system_prompt, temperature, max_tokens):
url = f"{BOOSAPI_V1}/chat/completions"
messages = []
if system_prompt:
messages.append({"role": "system", "content": system_prompt})
messages.append({"role": "user", "content": prompt})
payload = {
"model": model,
"messages": messages,
"temperature": temperature,
"max_tokens": max_tokens,
"stream": False,
}
try:
resp = requests.post(url, headers=HEADERS, json=payload, timeout=120)
raise_for_status_with_body(resp)
data = resp.json()
text = data["choices"][0]["message"]["content"]
return {"ui": {"text": (text,)}, "result": (text,)}
except Exception as e:
print(f"[BoosAPI] LLM chat failed: {e}")
raise
# ═════════════════════════════════════════════════════════════════════════
# Node: BoosAPITextToImage — 文生图 (ComfyUI 原生格式)
# ═════════════════════════════════════════════════════════════════════════
class BoosAPITextToImage:
"""输入文本提示词，通过 BoosAPI 生成图像，输出 ComfyUI IMAGE 格式"""
@classmethod
def INPUT_TYPES(cls):
return {
"required": {
"positive": ("STRING", {"multiline": True, "default": ""}),
"model": (model_choices("image"), {"default": default_model("image")}),
},
"optional": {
"negative": ("STRING", {"multiline": True, "default": ""}),
"size": (["1024x1024", "1792x1024", "1024x1792"], {"default": "1024x1024"}),
},
}
RETURN_TYPES = ("IMAGE",)
FUNCTION = "generate"
OUTPUT_NODE = True
CATEGORY = "BoosAPI"
def generate(self, positive, model, negative="", size="1024x1024"):
# Build prompt with negative guidance
prompt = positive
if negative:
prompt = f"{positive}\n避免: {negative}"
url = f"{BOOSAPI_V1}/images/generations"
payload = {
"model": model,
"prompt": prompt,
"n": 1,
"size": size,
"response_format": "b64_json",
}
try:
resp = requests.post(url, headers=HEADERS, json=payload, timeout=120)
raise_for_status_with_body(resp)
data = resp.json()
import base64
from io import BytesIO
import torch
from PIL import Image
import numpy as np
b64 = data["data"][0]["b64_json"]
img = Image.open(BytesIO(base64.b64decode(b64))).convert("RGB")
tensor = torch.from_numpy(np.array(img).astype("float32") / 255.0).unsqueeze(0)
return (tensor,)
except Exception as e:
print(f"[BoosAPI] T2I failed: {e}")
raise
# ═════════════════════════════════════════════════════════════════════════
# Register Nodes
# ═════════════════════════════════════════════════════════════════════════
NODE_CLASS_MAPPINGS = {
"BoosAPIImageGen": BoosAPIImageGen,
"BoosAPILLM": BoosAPILLM,
"BoosAPITextToImage": BoosAPITextToImage,
}
NODE_DISPLAY_NAME_MAPPINGS = {
"BoosAPIImageGen": "BoosAPI 图像生成",
"BoosAPILLM": "BoosAPI LLM 对话",
"BoosAPITextToImage": "BoosAPI 文生图",
}
__all__ = ["NODE_CLASS_MAPPINGS", "NODE_DISPLAY_NAME_MAPPINGS"]
config.toml
+76
View File
@@ -0,0 +1,76 @@
# 必填项保留；空字符串字段、有默认值的字段、与凭证相关的内容都从 toml 移走，
# 改用环境变量（BOOSAPI_<SECTION>__<KEY>）或后台 admin 界面写入数据库。
[server]
host = "0.0.0.0"
port = 4000
log_level = "info"
cors_origins = ["*"]
[db]
url = "sqlite:boosapi.db?mode=rwc"
max_connections = 10
ssl = false
[auth]
# 改成生产值前请先改 jwt_secret / auth_token / proxy_token，避免使用默认值。
jwt_secret = "boosapi-dev-secret-change-in-production"
jwt_expiry_hours = 72
auth_token = "boos4721"
proxy_token = "sk-boos4721"
[proxy]
upstream_timeout_secs = 300
first_byte_timeout_secs = 60
max_retries = 3
proxy_log_retention_days = 30
[payment]
enabled = true
# provider: "comfy_cloud" | "stripe"
provider = "comfy_cloud"
product_name_prefix = "BossAI 账户充值"
currency = "usd"
min_amount_usd = 1.0
max_amount_usd = 100000.0
order_timeout_minutes = 30
max_pending_orders = 3
success_path = "/user/recharge?payment=success&order={ORDER_ID}"
cancel_path = "/user/recharge?payment=cancel&order={ORDER_ID}"
comfy_customer_api_base_url = "https://api.comfy.org"
# 凭证统一走环境变量或后台「支付管理」写入；不要写在这里：
# BOOSAPI_PAYMENT__PUBLIC_BASE_URL
# BOOSAPI_PAYMENT__STRIPE_SECRET_KEY / STRIPE_WEBHOOK_SECRET
# BOOSAPI_PAYMENT__COMFY_CUSTOMER_TOKEN / COMFY_CUSTOMER_TOKEN_ENDPOINT
# BOOSAPI_PAYMENT__COMFY_FIREBASE_API_KEY / COMFY_OAUTH_REFRESH_TOKEN
# BOOSAPI_PAYMENT__COMFY_OAUTH_CLIENT_ID / COMFY_OAUTH_CLIENT_SECRET
# BOOSAPI_PAYMENT__COMFY_CHECKOUT_ENDPOINT
[comfyui]
enabled = false
# backend: "boosapi" | "cloud" | "runninghub" | "external" | "docker"
backend = "cloud"
python_bin = "python3"
port = 8188
extra_args = []
max_restarts = 5
base_url = "https://cloud.comfy.org"
api_key = "comfyui-cbe4ebb1e22ee4ef2dab4d9293a76d5272a25e5ec847ac57387ab2b30798d86f"
agent_model = "deepseek-v4-flash"
[pixelle_video]
enabled = true
# Pixelle-Video 单独启动：
# git clone https://github.com/AIDC-AI/Pixelle-Video /opt/Pixelle-Video
# cd /opt/Pixelle-Video && uv run python api/app.py --host 127.0.0.1 --port 18000
api_base_url = "http://127.0.0.1:18000"
frame_template = "1080x1920/image_default.html"
media_workflow = "selfhost/video_wan2.1_fusionx.json"
tts_workflow = "selfhost/tts_edge.json"
runninghub_media_workflow = "runninghub/video_wan2.1_fusionx.json"
runninghub_tts_workflow = "runninghub/tts_edge.json"
mode = "fixed"
n_scenes = 5
video_fps = 30
poll_interval_secs = 5
timeout_secs = 900
data/.gitkeep
View File
docker/.env.example
+21
View File
@@ -0,0 +1,21 @@
# Meta API Hub - Environment Variables
# Copy this file to .env and fill in your values
# cp .env.example .env
# Admin authentication token (required, change this!)
AUTH_TOKEN=change-me-admin-token
# Proxy API token used for OpenAI-compatible proxy endpoint (required, change this!)
PROXY_TOKEN=change-me-proxy-sk-token
PORT=4000
NOTIFY_COOLDOWN_SEC=300
ADMIN_IP_ALLOWLIST=
TELEGRAM_ENABLED=false
TELEGRAM_BOT_TOKEN=
TELEGRAM_CHAT_ID=
# Auto check-in cron (default: 8:00 AM every day)
CHECKIN_CRON=0 8 * * *
# Balance refresh cron (default: every hour)
BALANCE_REFRESH_CRON=0 * * * *
docker/.gitkeep
View File
docker/Dockerfile
+18
View File
@@ -0,0 +1,18 @@
# Build stage
FROM rust:1.85-slim-bookworm AS builder
WORKDIR /app
RUN apt-get update && apt-get install -y pkg-config libssl-dev
COPY Cargo.toml Cargo.lock ./
RUN mkdir src && echo "fn main() {}" > src/main.rs
RUN cargo build --release 2>/dev/null || true
COPY . .
RUN cargo build --release
# Runtime stage
FROM debian:bookworm-slim
RUN apt-get update && apt-get install -y ca-certificates && rm -rf /var/lib/apt/lists/*
WORKDIR /app
COPY --from=builder /app/target/release/boosapi /app/
COPY --from=builder /app/migrations /app/migrations
EXPOSE 4000
CMD ["/app/boosapi"]
docker/Dockerfile.comfyui.update
+33
View File
@@ -0,0 +1,33 @@
FROM boosapi-comfyui:multi-tenant
ARG COMFYUI_TAG=v0.22.2
WORKDIR /workspace/ComfyUI
COPY docker/build-comfyui-src /tmp/ComfyUI-updated
RUN find /workspace/ComfyUI -mindepth 1 \
! -path '/workspace/ComfyUI/venv' \
! -path '/workspace/ComfyUI/venv/*' \
-exec rm -rf {} + \
&& cp -a /tmp/ComfyUI-updated/. /workspace/ComfyUI/ \
&& rm -rf /tmp/ComfyUI-updated \
&& UV_INDEX_URL=https://pypi.tuna.tsinghua.edu.cn/simple \
UV_EXTRA_INDEX_URL=https://mirrors.tuna.tsinghua.edu.cn/pytorch-wheels/cpu/ \
uv pip install --python venv/bin/python -r requirements.txt \
&& UV_INDEX_URL=https://pypi.tuna.tsinghua.edu.cn/simple \
uv pip install --python venv/bin/python six \
&& mkdir -p /workspace/ComfyUI/custom_nodes/boosapi_nodes
COPY comfy/boosapi_comfy_nodes.py /workspace/ComfyUI/custom_nodes/boosapi_nodes/__init__.py
COPY scripts/comfyui/install-runninghub-template-nodes.sh /tmp/install-runninghub-template-nodes.sh
RUN bash /tmp/install-runninghub-template-nodes.sh \
&& rm -f /tmp/install-runninghub-template-nodes.sh
RUN python - <<'PY'
from pathlib import Path
path = Path("/workspace/ComfyUI/custom_nodes/boosapi_nodes/__init__.py")
if not path.exists():
raise SystemExit("BoosAPI custom node missing after ComfyUI update")
PY
docker/data-backup-20260515-151153.tar.gz
BIN
View File
Binary file not shown.
docker/docker-compose.override.yml
+9
View File
@@ -0,0 +1,9 @@
# docker-compose.override.yml
# This file is automatically picked up by Docker Compose during local development.
# It overrides the image reference in docker-compose.yml with a local build.
services:
boosapi:
image: ~
build:
context: ..
dockerfile: docker/Dockerfile
docs/superpowers/plans/2026-06-16-billing-closed-loop.md
+694
View File
@@ -0,0 +1,694 @@
# 计费闭环 实现计划
> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
**Goal:** 为 BoosAPI 建立 ledger-first 的双轨计费闭环（USD 池 + 工作流积分池），所有余额变动写统一流水账 `credit_ledger`。
**Architecture:** 新建 `credit_ledger`（唯一真相源）+ `user_credits`（积分缓存）+ `recharge_tiers`（充值档位）三张表。USD 轨沿用 `downstream_api_keys.max_cost/used_cost` 作热路径缓存，每笔变动同事务写一条 ledger。积分轨为工作流执行新增扣费/拦截。分 6 期，本计划详写第 1 期（地基），后 5 期为概要待细化。
**Tech Stack:** Rust (axum + sqlx + SQLite)、React + Vite 前端、in-memory SQLite 测试。
---
## 文件结构（第 1 期）
- 新建 `src/services/billing/ledger.rs` — ledger 写入 + 余额查询的唯一入口（`record_ledger_entry`、`ensure_ledger_schema`）。所有动余额的地方调它，保证"缓存 + ledger 同事务"不变量集中在一处。
- 修改 `src/services/billing/mod.rs` — `mod ledger;` 导出；`record_usage` 在写 usage_logs + increment 后，同事务补写 ledger(usd, consume)。
- 修改 `src/services/payment.rs` — `credit_user_balance` 加写 ledger(usd, recharge)。
- 修改 `src/routes/admin/users.rs` — `adjust_user_balance` 加写 ledger(usd, admin_adjust)。
- 测试：`src/services/billing/ledger.rs` 内 `#[cfg(test)] mod tests`（复用 in-memory SQLite 模式）。
---
## 第 1 期：地基（credit_ledger + user_credits 表 + USD 轨记账接入）
### Task 1：ledger 表结构 + 写入入口
**Files:**
- Create: `src/services/billing/ledger.rs`
- Modify: `src/services/billing/mod.rs`（顶部加 `pub mod ledger;`）
- [ ] **Step 1: 写失败测试** — 在 `src/services/billing/ledger.rs` 末尾：
```rust
#[cfg(test)]
mod tests {
use super::*;
use sqlx::sqlite::SqlitePoolOptions;
async fn mem_pool() -> SqlitePool {
let pool = SqlitePoolOptions::new()
.max_connections(1)
.connect("sqlite::memory:")
.await
.unwrap();
ensure_ledger_schema(&pool).await.unwrap();
pool
}
#[tokio::test]
async fn record_ledger_entry_writes_row_with_balance_snapshot() {
let pool = mem_pool().await;
let mut tx = pool.begin().await.unwrap();
record_ledger_entry(
&mut tx,
LedgerEntry {
user_id: 7,
track: "usd",
entry_type: "recharge",
amount: 10.0,
balance_after: 10.0,
ref_type: Some("stripe"),
ref_id: Some("cs_1"),
model: None,
operator: Some("system"),
note: None,
},
)
.await
.unwrap();
tx.commit().await.unwrap();
let row: (i64, String, String, f64, f64) = sqlx::query_as(
"SELECT user_id, track, entry_type, amount, balance_after
FROM credit_ledger WHERE user_id = 7",
)
.fetch_one(&pool)
.await
.unwrap();
assert_eq!(row, (7, "usd".into(), "recharge".into(), 10.0, 10.0));
}
}
```
- [ ] **Step 2: 运行测试确认失败**
Run: `cargo test -p boosapi --lib services::billing::ledger 2>&1 | tail -5`
Expected: 编译失败（`ensure_ledger_schema`/`record_ledger_entry`/`LedgerEntry` 未定义）。
- [ ] **Step 3: 写最小实现** — 在 `src/services/billing/ledger.rs` 顶部（tests 之前）：
```rust
use crate::error::AppResult;
use sqlx::{SqlitePool, Transaction};
/// One balance-changing event. Written to `credit_ledger` in the same
/// transaction that updates the cached balance, so ledger and cache never diverge.
pub struct LedgerEntry<'a> {
pub user_id: i64,
pub track: &'a str, // "usd" | "points"
pub entry_type: &'a str, // "recharge" | "admin_adjust" | "consume" | "refund" | "grant"
pub amount: f64, // +credit / -debit
pub balance_after: f64,
pub ref_type: Option<&'a str>,
pub ref_id: Option<&'a str>,
pub model: Option<&'a str>,
pub operator: Option<&'a str>,
pub note: Option<&'a str>,
}
pub async fn ensure_ledger_schema(db: &SqlitePool) -> AppResult<()> {
sqlx::query(
"CREATE TABLE IF NOT EXISTS credit_ledger (
id INTEGER PRIMARY KEY AUTOINCREMENT NOT NULL,
user_id INTEGER NOT NULL,
track TEXT NOT NULL,
entry_type TEXT NOT NULL,
amount REAL NOT NULL,
balance_after REAL NOT NULL,
ref_type TEXT,
ref_id TEXT,
model TEXT,
operator TEXT,
note TEXT,
created_at TEXT DEFAULT (datetime('now'))
)",
)
.execute(db)
.await?;
sqlx::query(
"CREATE INDEX IF NOT EXISTS credit_ledger_user_created_idx
ON credit_ledger (user_id, created_at DESC)",
)
.execute(db)
.await?;
sqlx::query(
"CREATE INDEX IF NOT EXISTS credit_ledger_track_type_idx
ON credit_ledger (track, entry_type)",
)
.execute(db)
.await?;
sqlx::query(
"CREATE TABLE IF NOT EXISTS user_credits (
user_id INTEGER PRIMARY KEY NOT NULL,
points_balance REAL NOT NULL DEFAULT 0,
points_total_recharged REAL NOT NULL DEFAULT 0,
updated_at TEXT DEFAULT (datetime('now'))
)",
)
.execute(db)
.await?;
Ok(())
}
/// Append one ledger row inside an existing transaction. Caller is responsible
/// for also updating the cached balance in the same `tx`.
pub async fn record_ledger_entry(
tx: &mut Transaction<'_, sqlx::Sqlite>,
entry: LedgerEntry<'_>,
) -> AppResult<()> {
sqlx::query(
"INSERT INTO credit_ledger
(user_id, track, entry_type, amount, balance_after,
ref_type, ref_id, model, operator, note)
VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?)",
)
.bind(entry.user_id)
.bind(entry.track)
.bind(entry.entry_type)
.bind(entry.amount)
.bind(entry.balance_after)
.bind(entry.ref_type)
.bind(entry.ref_id)
.bind(entry.model)
.bind(entry.operator)
.bind(entry.note)
.execute(&mut **tx)
.await?;
Ok(())
}
```
并在 `src/services/billing/mod.rs` 顶部加：`pub mod ledger;`
- [ ] **Step 4: 运行测试确认通过**
Run: `cargo test -p boosapi --lib services::billing::ledger 2>&1 | tail -5`
Expected: PASS（1 passed）。
- [ ] **Step 5: 提交**
```bash
git add src/services/billing/ledger.rs src/services/billing/mod.rs
git commit -m "feat(billing): credit_ledger schema + record_ledger_entry"
```
### Task 2：USD 消费接入 ledger（record_usage）
**Files:**
- Modify: `src/services/billing/mod.rs`（`record_usage`，行 ~48-77）
- [ ] **Step 1: 写失败测试** — 在 billing/mod.rs 的 tests mod 加：
```rust
#[tokio::test]
async fn record_usage_writes_consume_ledger_entry() {
let pool = billing_test_pool().await; // 复用现有测试 pool helper；若无则建 users+downstream_api_keys+usage_logs
let tracker = UsageTracker::new(std::sync::Arc::new(pool.clone()));
crate::services::billing::ledger::ensure_ledger_schema(&pool).await.unwrap();
// key_id=7 属于 user 9，max_cost=10 used_cost=2（由 helper 建好）
tracker.record_usage(7, "gpt-4o", 100, 50, 0.42).await.unwrap();
let row: (String, String, f64, Option<String>) = sqlx::query_as(
"SELECT track, entry_type, amount, model FROM credit_ledger
WHERE user_id = 9 ORDER BY id DESC LIMIT 1",
).fetch_one(&pool).await.unwrap();
assert_eq!(row.0, "usd");
assert_eq!(row.1, "consume");
assert_eq!(row.2, -0.42); // 消费为负
assert_eq!(row.3.as_deref(), Some("gpt-4o"));
}
```
注：若 billing/mod.rs 无现成 `billing_test_pool`，在 tests mod 加一个建 `users`/`downstream_api_keys`(含 user_id=9,key id=7 max_cost=10 used_cost=2)/`usage_logs` 的 helper（参照 payment.rs 的 payment_test_pool）。
- [ ] **Step 2: 运行确认失败**
Run: `cargo test -p boosapi --lib record_usage_writes_consume_ledger_entry 2>&1 | tail -5`
Expected: FAIL（credit_ledger 无 user 9 行 / 表不存在）。
- [ ] **Step 3: 实现** — `record_usage` 改为事务化，末尾补写 ledger。替换 record_usage 函数体为：
```rust
pub async fn record_usage(
&self,
key_id: i64,
model: impl Into<String>,
prompt_tokens: i64,
completion_tokens: i64,
cost: f64,
) -> AppResult<()> {
Self::ensure_schema(&self.db).await?;
crate::services::billing::ledger::ensure_ledger_schema(&self.db).await?;
let prompt_tokens = prompt_tokens.max(0);
let completion_tokens = completion_tokens.max(0);
let total_tokens = prompt_tokens + completion_tokens;
let cost = cost.max(0.0);
let model = model.into();
let mut tx = self.db.begin().await?;
sqlx::query(
"INSERT INTO usage_logs
(downstream_key_id, model, prompt_tokens, completion_tokens, total_tokens, cost)
VALUES (?, ?, ?, ?, ?, ?)",
)
.bind(key_id).bind(&model)
.bind(prompt_tokens).bind(completion_tokens).bind(total_tokens).bind(cost)
.execute(&mut *tx).await?;
sqlx::query(
"UPDATE downstream_api_keys
SET used_requests = COALESCE(used_requests,0)+1,
used_cost = COALESCE(used_cost,0)+?,
last_used_at = datetime('now'), updated_at = datetime('now')
WHERE id = ?",
).bind(cost).bind(key_id).execute(&mut *tx).await?;
// Resolve owning user + new used_cost for the ledger snapshot.
let owner: Option<(Option<i64>, Option<f64>, Option<f64>)> = sqlx::query_as(
"SELECT user_id, max_cost, used_cost FROM downstream_api_keys WHERE id = ?",
).bind(key_id).fetch_optional(&mut *tx).await?;
if let Some((Some(user_id), max_cost, used_cost)) = owner {
let used = used_cost.unwrap_or(0.0);
let remaining = max_cost.map(|m| (m - used).max(0.0)).unwrap_or(used);
crate::services::billing::ledger::record_ledger_entry(
&mut tx,
crate::services::billing::ledger::LedgerEntry {
user_id, track: "usd", entry_type: "consume",
amount: -cost, balance_after: remaining,
ref_type: Some("usage_log"), ref_id: None,
model: Some(&model), operator: Some("system"), note: None,
},
).await?;
}
tx.commit().await?;
Ok(())
}
```
（注：原 `increment_key_usage(&self.db, ...)` 调用被事务内 UPDATE 取代，删除该行。）
- [ ] **Step 4: 运行确认通过**
Run: `cargo test -p boosapi --lib record_usage 2>&1 | tail -6`
Expected: PASS。
- [ ] **Step 5: 提交**
```bash
git add src/services/billing/mod.rs
git commit -m "feat(billing): USD consume writes credit_ledger in one tx"
```
### Task 3：USD 充值接入 ledger（credit_user_balance）
**Files:**
- Modify: `src/services/payment.rs`（`credit_user_balance`，行 ~2167-2202）
- [ ] **Step 1: 写失败测试** — payment.rs tests mod（复用 payment_test_pool，user 9/key 7 max_cost=10）：
```rust
#[tokio::test]
async fn credit_user_balance_writes_recharge_ledger() {
let pool = payment_test_pool().await;
crate::services::billing::ledger::ensure_ledger_schema(&pool).await.unwrap();
let mut tx = pool.begin().await.unwrap();
credit_user_balance(&mut tx, 9, 20.0).await.unwrap();
tx.commit().await.unwrap();
let row: (String, String, f64) = sqlx::query_as(
"SELECT track, entry_type, amount FROM credit_ledger WHERE user_id = 9 ORDER BY id DESC LIMIT 1",
).fetch_one(&pool).await.unwrap();
assert_eq!(row, ("usd".into(), "recharge".into(), 20.0));
}
```
- [ ] **Step 2: 运行确认失败**
Run: `cargo test -p boosapi --lib credit_user_balance_writes_recharge_ledger 2>&1 | tail -5`
Expected: FAIL。
- [ ] **Step 3: 实现** — `credit_user_balance` 在 UPDATE max_cost 之后、`Ok(Some(key_id))` 之前插入 ledger 写入（已在事务 tx 内）：
```rust
// After the UPDATE that sets next_max_cost on the key:
crate::services::billing::ledger::record_ledger_entry(
tx,
crate::services::billing::ledger::LedgerEntry {
user_id, track: "usd", entry_type: "recharge",
amount: amount_usd.max(0.0),
balance_after: (next_max_cost - used_cost).max(0.0),
ref_type: Some("recharge_record"), ref_id: None,
model: None, operator: Some("system"), note: None,
},
).await?;
```
（`credit_user_balance` 已是 `tx: &mut Transaction`，直接传 `tx`。确保调用方在调用前已 `ensure_ledger_schema`，或在函数开头加一次幂等建表。）
- [ ] **Step 4: 运行确认通过**
Run: `cargo test -p boosapi --lib credit_user_balance 2>&1 | tail -6`
Expected: PASS（含已有的 recharge completion 测试）。
- [ ] **Step 5: 提交**
```bash
git add src/services/payment.rs
git commit -m "feat(billing): USD recharge writes credit_ledger"
```
### Task 4：USD 管理员调整接入 ledger（adjust_user_balance）
**Files:**
- Modify: `src/routes/admin/users.rs`（`adjust_user_balance`，行 ~820）
- [ ] **Step 1: 写失败测试** — users.rs tests mod：调 `adjust_user_balance(State, Path(9), Json{delta:5.0})` 后断言 credit_ledger 有一行 `(usd, admin_adjust, 5.0)`。（建表与 user/key 同 Task 3 helper。）
- [ ] **Step 2: 运行确认失败** — `cargo test -p boosapi --lib adjust_user_balance 2>&1 | tail -5` → FAIL。
- [ ] **Step 3: 实现** — `adjust_user_balance` 现在直接 `execute(&*state.db)`。改为事务：begin → UPDATE max_cost → `record_ledger_entry(track="usd", entry_type="admin_adjust", amount=delta, balance_after=next_max-used, operator=<管理员，暂用 "admin">)` → commit。函数开头 `ledger::ensure_ledger_schema(&state.db).await?;`。
- [ ] **Step 4: 运行确认通过** — `cargo test -p boosapi --lib adjust_user_balance 2>&1 | tail -6` → PASS。
- [ ] **Step 5: 提交**
```bash
git add src/routes/admin/users.rs
git commit -m "feat(billing): USD admin adjust writes credit_ledger"
```
### Task 5：全量回归
- [ ] **Step 1:** `cargo test 2>&1 | grep "test result"` → 全 ok。
- [ ] **Step 2:** `cargo build 2>&1 | tail -3` → Finished。
- [ ] **Step 3:** 提交（若有遗留）。
---
## 后续期次（概要，第 1 期落地后逐期细化为同样的 TDD 任务）
### 第 2 期：积分轨
- `user_credits` 已建表（Task 1）。新增 `adjust_user_credits`（admin 发放/增减，写 ledger points/admin_adjust）。
- comfy_cloud 确认到账 `admin_confirm_user_recharge` 改为加 `points_balance` + ledger(points, recharge)，受 config 开关 `payment.comfy_recharge_to_points` 控制（默认 true）；历史不迁移。
- 工作流积分单价 config（默认值 + 按工作流名分级映射）。
- `workflow/executor.rs` `run_workflow`：执行**前**查 `points_balance >= 单价`，不足返回 Forbidden「工作流积分不足」；执行**成功后**扣积分 + ledger(points, consume, model=工作流名)。
- 测试：拦截、扣费、充值进积分、管理员调整。
### 第 3 期：A 消费明细
- `GET /api/user/billing/ledger`（查本人 credit_ledger，track/type/时间过滤、分页）。
- `GET /api/user/billing/summary`（按天/模型聚合，双轨分开）。
- 扩展 `UsageRecords.tsx`：双轨切换 + 汇总卡 + 明细列表。
### 第 4 期：B 充值档位
- `recharge_tiers` 表（已在 spec，Task 1 未建，本期建）+ admin CRUD `/api/admin/recharge-tiers`。
- 用户充值档位从 DB 读（替代 env `USER_RECHARGE_OPTIONS`）。
- admin `RechargeTiers` 配置页 + `UserRecharge.tsx` 接 DB。
### 第 5 期：C 预警
- 余额接口（user_billing_summary 等）加 `lowBalance`（余额 < 阈值，config 默认 0.2）。
- Dashboard / UserRecharge / ComfyUIAgent 顶部预警条。
### 第 6 期：D 审计 + 对账
- `GET /api/admin/billing/ledger`（跨用户，过滤分页）+ admin `BillingAudit` 页。
- cron：拉 Comfy `/customers/balance` 总余额，与 points consume ledger 比对，偏差超阈值写 log + admin 告警标志（不自动改数据）。
---
## 自审
- **spec 覆盖**：第 1 期覆盖 spec「数据模型」+「USD 轨记账接入」三处（充值/消费/调整）；后 5 期概要逐条对应 spec 的积分轨/A/B/C/D + 对账。recharge_tiers 表 spec 列在数据模型，实现挪到第 4 期建（第 1 期用不到），已注明。
- **占位扫描**：第 1 期 Task 1-3 含完整代码；Task 4-5 用文字描述但步骤明确（adjust 与 Task 3 同模式，刻意不重复大段代码，执行时参照 Task 3）。后 5 期为概要，执行前细化。
- **类型一致**：`LedgerEntry` 字段、`record_ledger_entry`/`ensure_ledger_schema` 签名在 Task 1 定义，Task 2-4 一致引用。`track`/`entry_type` 取值（usd/points、recharge/consume/admin_adjust）全程一致。
---
## 第 2 期：积分轨（细化 TDD）
文件结构：
- `src/services/billing/ledger.rs` 加积分轨核心：`points_balance(db,user_id)`（读余额）、`apply_points_delta(db, user_id, delta, entry_type, model, operator, ref_*)`（事务内：UPSERT user_credits 余额 + 写 ledger(points)，返回新余额）。所有积分增减走这一个入口。
- `src/config.rs`：ComfyUIConfig 加 `workflow_points_cost`（默认单价）。
- `src/workflow/executor.rs`：run_workflow_with_progress 前置拦截 + 收尾扣积分。
- `src/services/payment.rs`：admin_confirm_user_recharge 改为加积分（受 config 开关）。
- `src/routes/admin/users.rs`：新增 `adjust_user_credits` handler + 路由。
### Task 6：积分轨核心 apply_points_delta + points_balance
**Files:** Modify `src/services/billing/ledger.rs`
- [ ] **Step1 失败测试**（ledger.rs tests mod）：
```rust
#[tokio::test]
async fn apply_points_delta_upserts_balance_and_writes_ledger() {
let pool = mem_pool().await;
// 首次 +100（充值）
let bal = apply_points_delta(&pool, 9, 100.0, "recharge", None, Some("system"), Some("recharge_record"), None).await.unwrap();
assert_eq!(bal, 100.0);
// 再 -30（消费）
let bal2 = apply_points_delta(&pool, 9, -30.0, "consume", Some("wf/video"), Some("system"), Some("workflow"), None).await.unwrap();
assert_eq!(bal2, 70.0);
// user_credits 缓存 = 70
let cached: f64 = sqlx::query_scalar("SELECT points_balance FROM user_credits WHERE user_id = 9").fetch_one(&pool).await.unwrap();
assert_eq!(cached, 70.0);
// ledger 两行
let n: i64 = sqlx::query_scalar("SELECT COUNT(*) FROM credit_ledger WHERE user_id=9 AND track='points'").fetch_one(&pool).await.unwrap();
assert_eq!(n, 2);
}
```
- [ ] **Step2** `cargo test -p boosapi --lib apply_points_delta_upserts 2>&1 | tail -6` → FAIL。
- [ ] **Step3 实现**（ledger.rs，tests 之前）：
```rust
/// Current points balance for a user (0 if no row yet).
pub async fn points_balance(db: &SqlitePool, user_id: i64) -> AppResult<f64> {
let bal: Option<f64> = sqlx::query_scalar(
"SELECT points_balance FROM user_credits WHERE user_id = ?",
)
.bind(user_id)
.fetch_optional(db)
.await?;
Ok(bal.unwrap_or(0.0))
}
/// Apply a points delta (+credit / -debit) atomically: upsert the cached
/// balance in `user_credits` and append one `credit_ledger(track=points)` row,
/// in a single transaction. Returns the new balance.
#[allow(clippy::too_many_arguments)]
pub async fn apply_points_delta(
db: &SqlitePool,
user_id: i64,
delta: f64,
entry_type: &str,
model: Option<&str>,
operator: Option<&str>,
ref_type: Option<&str>,
ref_id: Option<&str>,
) -> AppResult<f64> {
ensure_ledger_schema(db).await?;
let mut tx = db.begin().await?;
let current: f64 = sqlx::query_scalar(
"SELECT points_balance FROM user_credits WHERE user_id = ?",
)
.bind(user_id)
.fetch_optional(&mut *tx)
.await?
.unwrap_or(0.0);
let next = current + delta;
let total_recharged_inc = if delta > 0.0 && entry_type == "recharge" { delta } else { 0.0 };
sqlx::query(
"INSERT INTO user_credits (user_id, points_balance, points_total_recharged, updated_at)
VALUES (?, ?, ?, datetime('now'))
ON CONFLICT(user_id) DO UPDATE SET
points_balance = ?,
points_total_recharged = points_total_recharged + ?,
updated_at = datetime('now')",
)
.bind(user_id).bind(next).bind(total_recharged_inc)
.bind(next).bind(total_recharged_inc)
.execute(&mut *tx).await?;
record_ledger_entry(&mut tx, LedgerEntry {
user_id, track: "points", entry_type,
amount: delta, balance_after: next,
ref_type, ref_id, model, operator, note: None,
}).await?;
tx.commit().await?;
Ok(next)
}
```
- [ ] **Step4** `cargo test -p boosapi --lib apply_points_delta 2>&1 | tail -6` → PASS；`cargo build -j 2 | tail -2`。
- [ ] **Step5** `git add src/services/billing/ledger.rs && git commit -m "feat(billing): points track apply_points_delta + balance"`
### Task 7：工作流积分单价 config
**Files:** Modify `src/config.rs`
- [ ] **Step1** 测试：config 默认值测试（若 config.rs 有 default 测试则加断言；否则跳测试，靠编译）。
- [ ] **Step2/3 实现**：ComfyUIConfig 加字段 `#[serde(default = "default_workflow_points_cost")] pub workflow_points_cost: f64,`，default fn 返回 `10.0`；Default impl 里加 `workflow_points_cost: 10.0,`。
- [ ] **Step4** `cargo build -j 2 2>&1 | tail -3` → Finished（config 字段加完整个 crate 能编译）。
- [ ] **Step5** `git add src/config.rs && git commit -m "feat(billing): workflow_points_cost config"`
### Task 8：工作流执行前置拦截 + 成功扣积分
**Files:** Modify `src/workflow/executor.rs`
- [ ] **Step1 失败测试**：executor.rs tests mod（若无则建）。建 in-memory pool + user_credits/credit_ledger，构造一个最简 graph，`ctx.user_id=Some(9)`：
- 余额不足（0 积分，单价 10）→ run_workflow_with_progress 返回 Err（Forbidden 含"积分不足"）。
- 余额充足（100）→ 执行成功后 points_balance 变 90，credit_ledger 出现一行 (points, consume, -10)。
（若 executor 难以单测真实节点，则把"拦截"和"扣费"逻辑抽成小函数 `check_workflow_points(state, user_id, cost)` 和 `charge_workflow_points(state, user_id, cost, workflow_name)` 各自单测，run_workflow 调它们。优先抽函数单测。）
- [ ] **Step2** 确认 FAIL。
- [ ] **Step3 实现**：
- 在 run_workflow_with_progress 的 `validate_and_sort` 之后、`insert_run` 之前：若 `ctx.user_id` 是 Some 且 `ctx.charge_points`（见下）：`let cost = state.config.comfyui.workflow_points_cost; if cost > 0.0 { let bal = ledger::points_balance(&state.db, uid).await?; if bal < cost { return Err(AppError::Forbidden("工作流积分不足，请充值".into())); } }`
- 在 `complete_run` 之后、`Ok(run_public_id)` 之前：`if let Some(uid) = ctx.user_id { let cost = state.config.comfyui.workflow_points_cost; if cost > 0.0 { let _ = ledger::apply_points_delta(&state.db, uid, -cost, "consume", Some(&format!("workflow:{}", workflow_id)), Some("system"), Some("workflow_run"), Some(&run_public_id)).await; } }`（扣费 best-effort，失败记 log 不阻断已产出结果）。
- 注意：Admin 调用（builtin key，user_id 可能是 Some(admin) 或特殊）是否扣？按设计仅对普通用户扣。可用 RunContext 加 `pub charge_points: bool` 字段，run_context 构造时 User=>true / Admin=>false。models.rs RunContext 加该字段，两处构造（routes.rs run_context、workflow_ui.rs workflow_context）补 `charge_points`。
- [ ] **Step4** 测试 PASS + `cargo build -j 2`。
- [ ] **Step5** `git add src/workflow/executor.rs src/workflow/models.rs src/workflow/routes.rs src/routes/workflow_ui.rs && git commit -m "feat(billing): workflow points gating + charge"`
### Task 9：comfy 充值改加积分 + admin 积分调整
**Files:** Modify `src/services/payment.rs`、`src/routes/admin/users.rs`、`src/config.rs`(开关)、`src/routes/admin/mod.rs`(路由)
- [ ] **Step1 失败测试**：
- payment.rs：`admin_confirm_user_recharge` 确认后，credit_ledger 出现 (points, recharge, +amount)（而非 usd）；user_credits 增加。
- users.rs：`adjust_user_credits` handler 调用后 credit_ledger 出现 (points, admin_adjust)。
- [ ] **Step2** FAIL。
- [ ] **Step3 实现**：
- config 开关 `payment.comfy_recharge_to_points: bool`（默认 true）。
- `admin_confirm_user_recharge`：开关为 true 时改调 `ledger::apply_points_delta(db, user_id, amount_usd_as_points, "recharge", None, Some("admin"), Some("recharge_record"), Some(public_id))`（USD→积分换算：本期 1 USD = N 积分，N 用 config `payment.usd_to_points_rate` 默认 100；即 grant_points = amount_usd * rate）。开关 false 时维持原 credit_user_balance(USD)。**历史不迁移**。
- 新增 `adjust_user_credits(State, Path(id), Json{delta})` handler（仿 adjust_user_balance）→ `apply_points_delta(db,id,delta,"admin_adjust",None,Some("admin"),Some("manual"),None)`，返回 {success, data{userId, pointsBalance}}。
- admin/mod.rs 注册 `POST /api/admin/users/{id}/credits/adjust`。
- [ ] **Step4** 相关测试 + payment/users 模块全过 + build。
- [ ] **Step5** 分两个 commit 或一个：`git commit -m "feat(billing): comfy recharge to points + admin credit adjust"`
### Task 10：第 2 期全量回归
- [ ] `cargo test 2>&1 | grep "test result"` 全 ok；`cargo build -j 2 | tail -2` Finished。
---
## 第 3 期：A 消费明细(细化 TDD)
文件:`src/services/billing/ledger.rs`(加查询函数)、`src/routes/user/mod.rs`(加 2 路由)、`src/web/api.ts`(加 client)、`src/web/pages/UsageRecords.tsx`(扩展)。
### Task 11:ledger 查询函数(明细 + 聚合)
**Files:** Modify `src/services/billing/ledger.rs`
- [ ] **Step1 失败测试**(ledger.rs tests mod):
```rust
#[tokio::test]
async fn list_and_summarize_user_ledger() {
let pool = mem_pool().await;
apply_points_delta(&pool, 9, 100.0, "recharge", None, Some("system"), Some("rr"), None).await.unwrap();
apply_points_delta(&pool, 9, -10.0, "consume", Some("wf:1"), Some("system"), Some("run"), None).await.unwrap();
// 明细:user 9 两行,track=points
let rows = list_user_ledger(&pool, 9, None, None, 50, 0).await.unwrap();
assert_eq!(rows.len(), 2);
// 聚合:points 轨 consume 合计 -10
let sum = summarize_user_ledger(&pool, 9).await.unwrap();
assert!(sum.iter().any(|v| v["track"]=="points" && v["entryType"]=="consume"));
}
```
- [ ] **Step2** `cargo test -p boosapi --lib list_and_summarize_user_ledger 2>&1|tail -6` FAIL。
- [ ] **Step3 实现**(ledger.rs,tests 之前):
```rust
use serde_json::{json, Value};
/// List a user's ledger rows, newest first, optional track/entry_type filter + paging.
pub async fn list_user_ledger(
db: &SqlitePool, user_id: i64,
track: Option<&str>, entry_type: Option<&str>,
limit: i64, offset: i64,
) -> AppResult<Vec<Value>> {
ensure_ledger_schema(db).await?;
let limit = limit.clamp(1, 500);
let rows = sqlx::query(
"SELECT track, entry_type, amount, balance_after, model, operator, ref_type, ref_id, note, created_at
FROM credit_ledger
WHERE user_id = ?
AND (?1_track IS NULL OR track = ?1_track)
AND (?1_type IS NULL OR entry_type = ?1_type)
ORDER BY id DESC LIMIT ? OFFSET ?"
.replace("?1_track", "?2").replace("?1_type", "?3")
)
.bind(user_id).bind(track).bind(entry_type).bind(limit).bind(offset)
.fetch_all(db).await?;
use sqlx::Row;
Ok(rows.iter().map(|r| json!({
"track": r.try_get::<String,_>("track").unwrap_or_default(),
"entryType": r.try_get::<String,_>("entry_type").unwrap_or_default(),
"amount": r.try_get::<f64,_>("amount").unwrap_or(0.0),
"balanceAfter": r.try_get::<f64,_>("balance_after").unwrap_or(0.0),
"model": r.try_get::<Option<String>,_>("model").ok().flatten(),
"operator": r.try_get::<Option<String>,_>("operator").ok().flatten(),
"refType": r.try_get::<Option<String>,_>("ref_type").ok().flatten(),
"note": r.try_get::<Option<String>,_>("note").ok().flatten(),
"createdAt": r.try_get::<Option<String>,_>("created_at").ok().flatten(),
})).collect())
}
/// Aggregate a user's ledger by (track, entry_type): sum amount + count.
pub async fn summarize_user_ledger(db: &SqlitePool, user_id: i64) -> AppResult<Vec<Value>> {
ensure_ledger_schema(db).await?;
let rows = sqlx::query(
"SELECT track, entry_type, COALESCE(SUM(amount),0) AS total, COUNT(*) AS cnt
FROM credit_ledger WHERE user_id = ?
GROUP BY track, entry_type ORDER BY track, entry_type"
).bind(user_id).fetch_all(db).await?;
use sqlx::Row;
Ok(rows.iter().map(|r| json!({
"track": r.try_get::<String,_>("track").unwrap_or_default(),
"entryType": r.try_get::<String,_>("entry_type").unwrap_or_default(),
"total": r.try_get::<f64,_>("total").unwrap_or(0.0),
"count": r.try_get::<i64,_>("cnt").unwrap_or(0),
})).collect())
}
```
注:上面 SQL 的 named-param replace 写法若 sqlx 不接受,改用直白的可选过滤:用 `track.is_none() OR track = ?` 形式,bind 顺序 user_id, track, track, entry_type, entry_type, limit, offset（每个 Option bind 两次)。子代理按 sqlx 实际行为调整到能编译+测试过。
- [ ] **Step4** 测试 PASS + `cargo build -j 2`。
- [ ] **Step5** `git add src/services/billing/ledger.rs && git commit -m "feat(billing): user ledger list + summary queries"`
### Task 12:user 侧 billing 接口
**Files:** Modify `src/routes/user/mod.rs`(加 2 路由 + 2 handler)
- [ ] **Step1 失败测试**:user mod tests(若有 test_state/建表 helper 则复用)——构造 user JWT + ledger 数据,GET /api/user/billing/ledger 返回行,/summary 返回聚合。若 user mod 无现成集成测试框架,改为直接单测 handler 逻辑或跳测试靠 ledger.rs 的 Task11 测试覆盖,仅验证编译 + 路由注册。
- [ ] **Step2** FAIL/编译失败。
- [ ] **Step3 实现**:
```rust
async fn get_billing_ledger(State(state): State<AppState>, headers: HeaderMap, Query(q): Query<BillingLedgerQuery>) -> AppResult<Json<Value>> {
let user_id = current_user_id(&headers, &state)?;
let rows = crate::services::billing::ledger::list_user_ledger(
&state.db, user_id, q.track.as_deref(), q.entry_type.as_deref(),
q.limit.unwrap_or(100), q.offset.unwrap_or(0)).await?;
Ok(Json(json!({ "success": true, "records": rows })))
}
async fn get_billing_summary(State(state): State<AppState>, headers: HeaderMap) -> AppResult<Json<Value>> {
let user_id = current_user_id(&headers, &state)?;
let agg = crate::services::billing::ledger::summarize_user_ledger(&state.db, user_id).await?;
Ok(Json(json!({ "success": true, "summary": agg })))
}
```
+ `BillingLedgerQuery{ track:Option<String>, entry_type:Option<String>, limit:Option<i64>, offset:Option<i64> }`(serde Deserialize, rename_all camelCase 视前端传参)。
+ routes() 注册 `.route("/api/user/billing/ledger", get(get_billing_ledger)).route("/api/user/billing/summary", get(get_billing_summary))`。
- [ ] **Step4** `cargo test -p boosapi --lib 2>&1|command grep "test result"` + `cargo build -j 2`。
- [ ] **Step5** `git add src/routes/user/mod.rs && git commit -m "feat(billing): user billing ledger + summary endpoints"`
### Task 13:前端 api + UsageRecords 双轨展示
**Files:** Modify `src/web/api.ts`、`src/web/pages/UsageRecords.tsx`
- [ ] **Step1**:api.ts 的 userApi 加 `getBillingLedger(params)` → GET /api/user/billing/ledger、`getBillingSummary()` → /summary。
- [ ] **Step2**:UsageRecords.tsx 加一个"积分/USD"双轨切换 tab + 聚合汇总卡(用 getBillingSummary)+ ledger 明细列表(getBillingLedger)。保留现有 logs 视图作为 USD 明细来源之一,新增积分明细来自 ledger。具体 UI 复用现有 usage-records-* 样式。
- [ ] **Step3**:`npm run typecheck:web` 干净 + 现有 UsageRecords 测试不破坏(`npx vitest run src/web/pages/UsageRecords`)。
- [ ] **Step4** `git add src/web/api.ts src/web/pages/UsageRecords.tsx && git commit -m "feat(billing): UsageRecords dual-track ledger view"`
### Task 14:第3期回归
- [ ] `cargo test 2>&1|command grep "test result"` 全ok;`cargo build -j 2`;`npm run typecheck`。
docs/superpowers/plans/2026-06-17-comfy-cloud-adapter.md
+632
View File
@@ -0,0 +1,632 @@
# Comfy Cloud 工作流执行适配器 实现计划
> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
**Goal:** 在 BoosAPI 内实现 ComfyUI 原生协议 ↔ Comfy Cloud API 翻译适配器,让 Pixelle/comfykit 零改动通过 BoosAPI 调用 Comfy Cloud 执行工作流。
**Architecture:** 新增 `/comfy-cloud/{prompt,history,view}` 端点,内部翻译成 `cloud.comfy.org/api/*` + `X-API-Key`。Comfy Cloud 的 base_url + key 从站点管理(`platform='comfy_cloud'` 的 active 站点)读取。纯翻译函数单测,wiremock 集成测。
**Tech Stack:** Rust (axum, reqwest, sqlx, serde_json, wiremock, tokio)。
> **构建/测试:** `cargo build -j 2`、`cargo test -p boosapi --lib comfy_cloud`。分支 `feat/comfy-cloud-adapter`。
---
## 文件结构
- Create `src/services/comfy_cloud/mod.rs` — 模块导出。
- Create `src/services/comfy_cloud/site.rs` — `resolve_comfy_cloud_site` 读站点配置。
- Create `src/services/comfy_cloud/translate.rs` — `comfy_cloud_job_to_history` 纯翻译函数。
- Create `src/routes/comfy_cloud_adapter.rs` — 三个适配端点 + `routes()`。
- Modify `src/services/mod.rs` — 加 `pub mod comfy_cloud;`。
- Modify `src/routes/mod.rs` — 加 `mod comfy_cloud_adapter;` + `.merge(...)`。
- Modify `src/web/pages/Sites.tsx` — `SITE_PLATFORM_OPTIONS` 加 `comfy_cloud` 选项。
---
<!-- TASKS -->
## Task 1: 站点配置读取 `resolve_comfy_cloud_site`
**Files:**
- Create: `src/services/comfy_cloud/mod.rs`
- Create: `src/services/comfy_cloud/site.rs`
- Modify: `src/services/mod.rs`
- [ ] **Step 1: `src/services/mod.rs` 末尾加模块声明**
```rust
pub mod comfy_cloud;
```
- [ ] **Step 2: 写 `src/services/comfy_cloud/mod.rs`**
```rust
//! Comfy Cloud 工作流执行适配器 service 层。
pub mod site;
pub mod translate;
```
- [ ] **Step 3: 写失败测试 `src/services/comfy_cloud/site.rs`**
```rust
use crate::error::{AppError, AppResult};
use sqlx::SqlitePool;
/// 解析 Comfy Cloud 站点配置,返回 (base_url, api_key)。
/// 取 platform='comfy_cloud' 且 status='active' 的站点。
pub async fn resolve_comfy_cloud_site(db: &SqlitePool) -> AppResult<(String, String)> {
let row: Option<(String, Option<String>)> = sqlx::query_as(
"SELECT url, api_key FROM sites
WHERE platform = 'comfy_cloud' AND status = 'active'
ORDER BY COALESCE(sort_order, 0), id LIMIT 1",
)
.fetch_optional(db)
.await?;
let (url, api_key) = row.ok_or_else(|| {
AppError::ServiceUnavailable("未配置 Comfy Cloud 站点(站点管理添加 comfy_cloud 平台)".into())
})?;
let api_key = api_key
.map(|k| k.trim().to_string())
.filter(|k| !k.is_empty())
.ok_or_else(|| AppError::ServiceUnavailable("Comfy Cloud 站点缺少 API Key".into()))?;
let base_url = url.trim().trim_end_matches('/').to_string();
Ok((base_url, api_key))
}
#[cfg(test)]
mod tests {
use super::*;
use sqlx::sqlite::SqlitePoolOptions;
async fn pool() -> SqlitePool {
let pool = SqlitePoolOptions::new().max_connections(1).connect("sqlite::memory:").await.unwrap();
sqlx::query("CREATE TABLE sites (id INTEGER PRIMARY KEY AUTOINCREMENT, name TEXT, url TEXT NOT NULL, platform TEXT NOT NULL, status TEXT NOT NULL, api_key TEXT, sort_order INTEGER)")
.execute(&pool).await.unwrap();
pool
}
#[tokio::test]
async fn resolves_active_comfy_cloud_site() {
let pool = pool().await;
sqlx::query("INSERT INTO sites (name,url,platform,status,api_key) VALUES ('cc','https://cloud.comfy.org/','comfy_cloud','active','key-123')")
.execute(&pool).await.unwrap();
let (url, key) = resolve_comfy_cloud_site(&pool).await.unwrap();
assert_eq!(url, "https://cloud.comfy.org");
assert_eq!(key, "key-123");
}
#[tokio::test]
async fn errors_when_not_configured() {
let pool = pool().await;
let r = resolve_comfy_cloud_site(&pool).await;
assert!(matches!(r, Err(AppError::ServiceUnavailable(_))));
}
}
```
- [ ] **Step 4: 运行测试,确认失败**
Run: `cargo test -p boosapi --lib services::comfy_cloud::site 2>&1 | tail -15`
Expected: FAIL —— 模块未挂载/函数未定义(编译错误)。
- [ ] **Step 5: 实现**
Step 3 的函数体即实现(测试与实现同文件)。确认 `src/services/comfy_cloud/mod.rs` 已 `pub mod site;`。
- [ ] **Step 6: 运行测试,确认通过**
Run: `cargo test -p boosapi --lib services::comfy_cloud::site 2>&1 | tail -10`
Expected: PASS(2 个测试)。
- [ ] **Step 7: Commit**
```bash
git add src/services/mod.rs src/services/comfy_cloud/mod.rs src/services/comfy_cloud/site.rs
git commit -m "feat(comfy-cloud): 站点配置读取 resolve_comfy_cloud_site"
```
<!-- T2 -->
## Task 2: 翻译函数 `comfy_cloud_job_to_history`
**Files:**
- Create: `src/services/comfy_cloud/translate.rs`
- [ ] **Step 1: 写失败测试 `src/services/comfy_cloud/translate.rs`**
```rust
use serde_json::{json, Value};
/// 把 Comfy Cloud 的 job status(+ 完成时的 jobs detail outputs)翻译成
/// ComfyUI 原生 /history/{id} 的形状。
///
/// - status pending/in_progress → 返回空对象 {}(comfykit 据此继续轮询)
/// - status completed → { "{id}": { "status": {completed:true, status_str:"success"}, "outputs": {...} } }
/// - status failed/cancelled → { "{id}": { "status": {completed:false, status_str:"error"} } }
pub fn comfy_cloud_job_to_history(
prompt_id: &str,
status: &str,
outputs: Option<&Value>,
) -> Value {
match status {
"completed" => json!({
prompt_id: {
"status": { "completed": true, "status_str": "success" },
"outputs": outputs.cloned().unwrap_or_else(|| json!({})),
}
}),
"failed" | "cancelled" => json!({
prompt_id: {
"status": { "completed": false, "status_str": "error" },
"outputs": {},
}
}),
_ => json!({}),
}
}
#[cfg(test)]
mod tests {
use super::*;
#[test]
fn in_progress_returns_empty() {
assert_eq!(comfy_cloud_job_to_history("p1", "in_progress", None), json!({}));
assert_eq!(comfy_cloud_job_to_history("p1", "pending", None), json!({}));
}
#[test]
fn completed_wraps_outputs() {
let outputs = json!({ "9": { "images": [{ "filename": "a.png", "subfolder": "", "type": "output" }] } });
let h = comfy_cloud_job_to_history("p1", "completed", Some(&outputs));
assert_eq!(h["p1"]["status"]["completed"], true);
assert_eq!(h["p1"]["outputs"]["9"]["images"][0]["filename"], "a.png");
}
#[test]
fn failed_marks_error() {
let h = comfy_cloud_job_to_history("p1", "failed", None);
assert_eq!(h["p1"]["status"]["status_str"], "error");
assert_eq!(h["p1"]["status"]["completed"], false);
}
}
```
- [ ] **Step 2: 运行测试,确认失败**
Run: `cargo test -p boosapi --lib services::comfy_cloud::translate 2>&1 | tail -15`
Expected: FAIL —— 模块未挂载/函数未定义。
- [ ] **Step 3: 实现**
Step 1 的函数体即实现。确认 `mod.rs` 已 `pub mod translate;`(Task 1 Step 2 已加)。
- [ ] **Step 4: 运行测试,确认通过**
Run: `cargo test -p boosapi --lib services::comfy_cloud::translate 2>&1 | tail -10`
Expected: PASS(3 个测试)。
- [ ] **Step 5: Commit**
```bash
git add src/services/comfy_cloud/translate.rs
git commit -m "feat(comfy-cloud): job→ComfyUI history 翻译函数"
```
<!-- T3 -->
## Task 3: 适配端点骨架 + `POST /comfy-cloud/prompt`
**Files:**
- Create: `src/routes/comfy_cloud_adapter.rs`
- [ ] **Step 1: 写骨架 + 测试 `src/routes/comfy_cloud_adapter.rs`**
```rust
use crate::error::{AppError, AppResult};
use crate::services::comfy_cloud::site::resolve_comfy_cloud_site;
use crate::services::comfy_cloud::translate::comfy_cloud_job_to_history;
use crate::AppState;
use axum::{
body::Body,
extract::{Path, RawQuery, State},
http::{header, StatusCode},
response::Response,
routing::{get, post},
Json, Router,
};
use serde_json::Value;
pub fn routes() -> Router<AppState> {
Router::new()
.route("/comfy-cloud/prompt", post(submit_prompt))
.route("/comfy-cloud/history/{prompt_id}", get(get_history))
.route("/comfy-cloud/view", get(get_view))
}
fn client() -> reqwest::Client {
reqwest::Client::builder()
.timeout(std::time::Duration::from_secs(120))
.build()
.unwrap_or_else(|_| reqwest::Client::new())
}
async fn submit_prompt(
State(state): State<AppState>,
Json(body): Json<Value>,
) -> AppResult<Json<Value>> {
let (base_url, api_key) = resolve_comfy_cloud_site(&state.db).await?;
let resp = client()
.post(format!("{base_url}/api/prompt"))
.header("X-API-Key", api_key)
.json(&body)
.send()
.await
.map_err(|e| AppError::UpstreamError(e.to_string()))?;
let status = resp.status();
let text = resp.text().await.map_err(|e| AppError::UpstreamError(e.to_string()))?;
if !status.is_success() {
return Err(AppError::UpstreamError(format!("Comfy Cloud prompt [{status}]: {text}")));
}
let value: Value = serde_json::from_str(&text).unwrap_or_else(|_| serde_json::json!({ "body": text }));
Ok(Json(value))
}
#[cfg(test)]
mod tests {
use super::*;
use wiremock::matchers::{header as match_header, method, path};
use wiremock::{Mock, MockServer, ResponseTemplate};
use sqlx::sqlite::SqlitePoolOptions;
async fn db_with_site(base_url: &str) -> sqlx::SqlitePool {
let pool = SqlitePoolOptions::new().max_connections(1).connect("sqlite::memory:").await.unwrap();
sqlx::query("CREATE TABLE sites (id INTEGER PRIMARY KEY AUTOINCREMENT, name TEXT, url TEXT NOT NULL, platform TEXT NOT NULL, status TEXT NOT NULL, api_key TEXT, sort_order INTEGER)")
.execute(&pool).await.unwrap();
sqlx::query("INSERT INTO sites (name,url,platform,status,api_key) VALUES ('cc',?,'comfy_cloud','active','key-123')")
.bind(base_url).execute(&pool).await.unwrap();
pool
}
#[tokio::test]
async fn submit_forwards_with_api_key() {
let server = MockServer::start().await;
Mock::given(method("POST"))
.and(path("/api/prompt"))
.and(match_header("X-API-Key", "key-123"))
.respond_with(ResponseTemplate::new(200).set_body_json(serde_json::json!({ "prompt_id": "p1" })))
.mount(&server).await;
let pool = db_with_site(&server.uri()).await;
let (base_url, api_key) = resolve_comfy_cloud_site(&pool).await.unwrap();
// 直接验证转发契约(handler 依赖 AppState,这里测底层契约)
let resp = client().post(format!("{base_url}/api/prompt"))
.header("X-API-Key", api_key)
.json(&serde_json::json!({ "prompt": {} }))
.send().await.unwrap();
let v: Value = resp.json().await.unwrap();
assert_eq!(v["prompt_id"], "p1");
}
}
```
> 注:`submit_prompt` handler 需 `AppState`,完整 handler 走 Task 6 联调验证;本 task 的
> wiremock 测试验证「X-API-Key 注入 + `/api/prompt` 路径 + prompt_id 透传」这一核心契约。
- [ ] **Step 2: 运行测试,确认失败**
Run: `cargo test -p boosapi --lib routes::comfy_cloud_adapter 2>&1 | tail -15`
Expected: FAIL —— 模块未挂载(`get_history`/`get_view` 未定义,编译错误)。
> 因 `routes()` 引用了 Task 4/5 的 `get_history`/`get_view`,本 task 先写它们的空桩
> 让编译过(Step 3),Task 4/5 再填实现。
- [ ] **Step 3: 加 `get_history`/`get_view` 空桩(接在 `submit_prompt` 之后,让编译通过)**
```rust
async fn get_history(
State(state): State<AppState>,
Path(prompt_id): Path<String>,
) -> AppResult<Json<Value>> {
let _ = (&state, &prompt_id);
Ok(Json(serde_json::json!({})))
}
async fn get_view(
State(state): State<AppState>,
RawQuery(query): RawQuery,
) -> AppResult<Response> {
let _ = (&state, &query);
Ok(Response::builder().status(StatusCode::NOT_IMPLEMENTED).body(Body::empty())
.map_err(|e| AppError::Internal(anyhow::anyhow!(e)))?)
}
```
- [ ] **Step 4: 运行测试,确认通过**
Run: `cargo test -p boosapi --lib routes::comfy_cloud_adapter 2>&1 | tail -10`
Expected: PASS(1 个测试)。
> 此时 `routes::comfy_cloud_adapter` 模块还没挂进 `routes/mod.rs`,测试是模块内单测,
> 不需要挂载即可跑。挂载在 Task 6。
- [ ] **Step 5: Commit**
```bash
git add src/routes/comfy_cloud_adapter.rs
git commit -m "feat(comfy-cloud): 适配端点骨架 + POST /prompt 转发"
```
<!-- T4 -->
## Task 4: `GET /comfy-cloud/history/{id}` 轮询翻译
**Files:**
- Modify: `src/routes/comfy_cloud_adapter.rs`
- [ ] **Step 1: 写失败测试(加到测试模块内)**
```rust
#[tokio::test]
async fn history_in_progress_then_completed() {
let server = MockServer::start().await;
// 状态查询:completed
Mock::given(method("GET"))
.and(path("/api/job/p1/status"))
.and(match_header("X-API-Key", "key-123"))
.respond_with(ResponseTemplate::new(200).set_body_json(serde_json::json!({ "status": "completed" })))
.mount(&server).await;
// 详情:outputs
Mock::given(method("GET"))
.and(path("/api/jobs/p1"))
.respond_with(ResponseTemplate::new(200).set_body_json(serde_json::json!({
"outputs": { "9": { "images": [{ "filename": "a.png", "subfolder": "", "type": "output" }] } }
})))
.mount(&server).await;
let pool = db_with_site(&server.uri()).await;
let history = fetch_history(&pool, "p1").await.unwrap();
assert_eq!(history["p1"]["status"]["completed"], true);
assert_eq!(history["p1"]["outputs"]["9"]["images"][0]["filename"], "a.png");
}
```
- [ ] **Step 2: 运行测试,确认失败**
Run: `cargo test -p boosapi --lib routes::comfy_cloud_adapter::tests::history 2>&1 | tail -15`
Expected: FAIL —— `fetch_history` 未定义。
- [ ] **Step 3: 实现 `fetch_history` + 替换 `get_history` 空桩**
把 Task 3 的 `get_history` 空桩替换为:
```rust
async fn fetch_history(db: &sqlx::SqlitePool, prompt_id: &str) -> AppResult<Value> {
let (base_url, api_key) = resolve_comfy_cloud_site(db).await?;
let http = client();
let status_resp = http
.get(format!("{base_url}/api/job/{prompt_id}/status"))
.header("X-API-Key", &api_key)
.send().await
.map_err(|e| AppError::UpstreamError(e.to_string()))?;
if !status_resp.status().is_success() {
let st = status_resp.status();
let body = status_resp.text().await.unwrap_or_default();
return Err(AppError::UpstreamError(format!("Comfy Cloud status [{st}]: {body}")));
}
let status_json: Value = status_resp.json().await.map_err(|e| AppError::UpstreamError(e.to_string()))?;
let status = status_json.get("status").and_then(Value::as_str).unwrap_or("in_progress");
if status != "completed" {
return Ok(comfy_cloud_job_to_history(prompt_id, status, None));
}
let detail_resp = http
.get(format!("{base_url}/api/jobs/{prompt_id}"))
.header("X-API-Key", &api_key)
.send().await
.map_err(|e| AppError::UpstreamError(e.to_string()))?;
let detail_json: Value = detail_resp.json().await.map_err(|e| AppError::UpstreamError(e.to_string()))?;
let outputs = detail_json.get("outputs");
Ok(comfy_cloud_job_to_history(prompt_id, status, outputs))
}
async fn get_history(
State(state): State<AppState>,
Path(prompt_id): Path<String>,
) -> AppResult<Json<Value>> {
Ok(Json(fetch_history(&state.db, &prompt_id).await?))
}
```
- [ ] **Step 4: 运行测试,确认通过**
Run: `cargo test -p boosapi --lib routes::comfy_cloud_adapter 2>&1 | tail -10`
Expected: PASS(submit + history 共 2 个测试)。
- [ ] **Step 5: Commit**
```bash
git add src/routes/comfy_cloud_adapter.rs
git commit -m "feat(comfy-cloud): /history 轮询翻译(status+jobs→history)"
```
<!-- T5 -->
## Task 5: `GET /comfy-cloud/view` 产出文件透传
**Files:**
- Modify: `src/routes/comfy_cloud_adapter.rs`
- [ ] **Step 1: 写失败测试(加到测试模块内)**
```rust
#[tokio::test]
async fn view_proxies_file_bytes() {
let server = MockServer::start().await;
Mock::given(method("GET"))
.and(path("/api/view"))
.and(match_header("X-API-Key", "key-123"))
.respond_with(ResponseTemplate::new(200)
.insert_header("content-type", "image/png")
.set_body_bytes(b"PNGDATA".to_vec()))
.mount(&server).await;
let pool = db_with_site(&server.uri()).await;
let (mime, bytes) = fetch_view(&pool, Some("filename=a.png&type=output")).await.unwrap();
assert_eq!(mime, "image/png");
assert_eq!(bytes, b"PNGDATA");
}
```
- [ ] **Step 2: 运行测试,确认失败**
Run: `cargo test -p boosapi --lib routes::comfy_cloud_adapter::tests::view 2>&1 | tail -15`
Expected: FAIL —— `fetch_view` 未定义。
- [ ] **Step 3: 实现 `fetch_view` + 替换 `get_view` 空桩**
把 Task 3 的 `get_view` 空桩替换为:
```rust
async fn fetch_view(db: &sqlx::SqlitePool, query: Option<&str>) -> AppResult<(String, Vec<u8>)> {
let (base_url, api_key) = resolve_comfy_cloud_site(db).await?;
let q = query.unwrap_or("");
let url = if q.is_empty() { format!("{base_url}/api/view") } else { format!("{base_url}/api/view?{q}") };
let resp = client()
.get(url)
.header("X-API-Key", api_key)
.send().await
.map_err(|e| AppError::UpstreamError(e.to_string()))?;
if !resp.status().is_success() {
let st = resp.status();
return Err(AppError::UpstreamError(format!("Comfy Cloud view [{st}]")));
}
let mime = resp
.headers()
.get(header::CONTENT_TYPE)
.and_then(|v| v.to_str().ok())
.unwrap_or("application/octet-stream")
.to_string();
let bytes = resp.bytes().await.map_err(|e| AppError::UpstreamError(e.to_string()))?.to_vec();
Ok((mime, bytes))
}
async fn get_view(
State(state): State<AppState>,
RawQuery(query): RawQuery,
) -> AppResult<Response> {
let (mime, bytes) = fetch_view(&state.db, query.as_deref()).await?;
Response::builder()
.status(StatusCode::OK)
.header(header::CONTENT_TYPE, mime)
.body(Body::from(bytes))
.map_err(|e| AppError::Internal(anyhow::anyhow!(e)))
}
```
> reqwest 默认跟随 302,所以 Comfy Cloud `/api/view` 的签名 URL 跳转会被自动跟随,
> 最终拿到文件字节。无需手动处理 Location。
- [ ] **Step 4: 运行测试,确认通过**
Run: `cargo test -p boosapi --lib routes::comfy_cloud_adapter 2>&1 | tail -10`
Expected: PASS(submit + history + view 共 3 个测试)。
- [ ] **Step 5: Commit**
```bash
git add src/routes/comfy_cloud_adapter.rs
git commit -m "feat(comfy-cloud): /view 产出文件透传"
```
<!-- T6 -->
## Task 6: 挂载路由 + 前端平台选项 + 全量验证
**Files:**
- Modify: `src/routes/mod.rs`
- Modify: `src/web/pages/Sites.tsx`
- [ ] **Step 1: `src/routes/mod.rs` 顶部模块声明区加**
```rust
mod comfy_cloud_adapter;
```
- [ ] **Step 2: `build_router` 的 merge 链里加(`.merge(picture_agent::routes())` 附近)**
```rust
.merge(comfy_cloud_adapter::routes())
```
- [ ] **Step 3: 前端 `SITE_PLATFORM_OPTIONS` 加 comfy_cloud 选项**
在 `src/web/pages/Sites.tsx` 的 `SITE_PLATFORM_OPTIONS` 数组(约 line 700-710,
`{ value: 'cliproxyapi', ... }` 附近)加一项:
```tsx
{ value: 'comfy_cloud', label: 'Comfy Cloud', description: '工作流执行 API（数字人/图片视频）' },
```
- [ ] **Step 4: 后端全量构建 + comfy_cloud 测试**
Run: `cargo build -j 2 2>&1 | tail -3 && cargo test -p boosapi --lib comfy_cloud 2>&1 | command grep "test result"`
Expected: `Finished`;comfy_cloud service + routes 测试全 PASS。
- [ ] **Step 5: 前端 typecheck**
Run: `npm run typecheck:web 2>&1 | tail -5`
Expected: 无错误。
- [ ] **Step 6: Commit**
```bash
git add src/routes/mod.rs src/web/pages/Sites.tsx
git commit -m "feat(comfy-cloud): 挂载适配路由 + 站点管理 comfy_cloud 平台选项"
```
---
## Task 7: 真实联调(手动验证,非自动测试)
> 这一步需要运行中的 BoosAPI + Pixelle,属手动验证。前 6 个 task 完成且 push 后执行。
- [ ] **Step 1: 站点管理添加 Comfy Cloud 站点**
在管理控制台「站点管理」新增站点:平台选 `Comfy Cloud`,URL 填 `https://cloud.comfy.org`,
API Key 填有效的 Comfy Cloud key(`X-API-Key`),状态 active。
- [ ] **Step 2: 改 Pixelle config.yaml 的 comfyui_url**
把 `/opt/Pixelle-Video/config.yaml` 的 `comfyui.comfyui_url` 改为
`http://<boosapi-host>:<port>/comfy-cloud`(指向 BoosAPI 适配端点),
然后 `docker compose restart api`(在 `/opt/Pixelle-Video`)。
- [ ] **Step 3: 跑一次 selfhost 视频生成**
从前端触发数字人/图片 selfhost 工作流生成视频,确认:
- 不再出现 `401 AuthenticationRequired`。
- 任务能提交(拿到 prompt_id)、轮询到 completed、取回产出文件。
- [ ] **Step 4: 失败排查指引(若仍报错)**
- 仍 401:检查站点 api_key 是否为有效 Comfy Cloud key(`curl -H "X-API-Key: KEY" https://cloud.comfy.org/api/user` 应回 200)。
- 404/路径错:确认 Pixelle comfyui_url 末尾无多余 `/`,BoosAPI 适配端点前缀为 `/comfy-cloud`。
- 取不到产出:看 BoosAPI 日志里 `/api/jobs/{id}` 的响应 outputs 结构,必要时调 translate 映射。
---
## 完成标准
- 后端:`resolve_comfy_cloud_site` + `comfy_cloud_job_to_history` + 三个适配端点
(`/comfy-cloud/{prompt,history,view}`)实现并测试通过,`cargo build -j 2` 干净。
- 前端:站点管理可选 `comfy_cloud` 平台,`npm run typecheck:web` 干净。
- 联调:Pixelle 指向 BoosAPI 适配端点后,selfhost 视频生成不再 401 且能出片。
- 全部提交在 `feat/comfy-cloud-adapter` 分支。
docs/superpowers/plans/2026-06-18-digital-human-comfy-video-entry.md
+241
View File
@@ -0,0 +1,241 @@
# 数字人接入 Comfy Cloud 视频工作流(完整视频入口)实现计划
> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
**Goal:** 给 BoosAPI 数字人加「视频工作流」入口,让用户选 `comfy/video_digital_ltx2.json` 触发「肖像图+旁白音频→LTX2.3 说话视频」,贯穿前端→BoosAPI 后端→Pixelle 三层。
**Architecture:** 前端 `DigitalHuman.tsx` 加可选「视频工作流」选择器(列 `video_*`),提交 `api_video_workflow`;BoosAPI `digital_human.rs` 的 `pixelle_request_body` 透传该字段;Pixelle `asset_based.py` 对 `comfy/` 视频工作流也注入 `audio_path`。视频入口默认空=不启用,保持现有「图片+HTML 合成」向后兼容。
**Tech Stack:** React/TS(BoosAPI 前端)、Rust/axum(BoosAPI 后端)、Python(Pixelle,容器内)。
> **环境:** BoosAPI 仓库 `/root/metapi`,前端 `src/web`,后端 `src/routes`。Pixelle 在 Docker 容器 `pixelle-video-api`,源码 `/app/pixelle_video`(镜像内置,改后 `docker compose restart api`,备份到 `/opt/Pixelle-Video/patches/`)。构建:前端 `npm run typecheck:web`,后端 `cargo build -j 2`(-j 2 防 OOM)。分支 `feat/comfy-cloud-adapter`。
> **前置(已完成):** comfy-cloud 适配器、`comfy/video_digital_ltx2.json`(probe 通过)、media.py 转发 image_path。
---
## 文件结构
- Modify `src/web/pages/DigitalHuman.tsx` — 加 `apiVideoWorkflow` state + 「视频工作流」选择器 + payload 字段 + draft 持久化。
- Modify `src/routes/digital_human.rs` — `pixelle_request_body` 转发 `api_video_workflow`。
- Modify(容器内)`/app/pixelle_video/pipelines/asset_based.py` — comfy 视频工作流注入 audio_path。
---
<!-- TASKS -->
## Task 1: 前端加「视频工作流」选择器 + 提交字段
**Files:**
- Modify: `src/web/pages/DigitalHuman.tsx`
- [ ] **Step 1: `DigitalHumanDraft` type 加字段(~line 34 附近,imageWorkflow 旁)**
找到 `imageWorkflow?: string;`(约 line 34),其后加一行:
```ts
apiVideoWorkflow?: string;
```
- [ ] **Step 2: 加 state(~line 370,imageWorkflow useState 旁)**
找到 `const [imageWorkflow, setImageWorkflow] = useState(draftRef.current.imageWorkflow || '');`(约 line 370),其后加:
```ts
const [apiVideoWorkflow, setApiVideoWorkflow] = useState(draftRef.current.apiVideoWorkflow || '');
```
- [ ] **Step 3: draft 持久化加字段(~line 462 写入 + ~line 480 依赖数组)**
在 `writeDigitalHumanDraft({...})` 对象里(约 line 462),`imageWorkflow,` 后加 `apiVideoWorkflow,`;
在该 useEffect 的依赖数组里(约 line 480),`imageWorkflow,` 后同样加 `apiVideoWorkflow,`。
- [ ] **Step 4: 提交 payload 加字段(~line 570 payload 对象)**
找到 payload 对象里的 `media_workflow: imageWorkflow || undefined,`(约 line 575),其后加:
```ts
api_video_workflow: apiVideoWorkflow || undefined,
```
- [ ] **Step 5: 加「视频工作流」选择器 UI(图片工作流 select 之后,~line 1012)**
找到「图片工作流」那个 `<label className="digital-human-field">...select...</label>` 块结束处
(约 line 1012,`</label>` 后),插入新选择器:
```tsx
<label className="digital-human-field">
<span>视频工作流（可选，生成说话视频）</span>
<select value={apiVideoWorkflow} onChange={(event) => setApiVideoWorkflow(event.target.value)}>
<option value="">不生成视频（仅图片合成）</option>
{mediaWorkflows
.filter((wf) => wf.name.toLowerCase().includes('video'))
.map((wf) => (
<option key={workflowValue(wf)} value={workflowValue(wf)}>{pickItemLabel(wf)}{wf.source ? ` · ${wf.source}` : ''}</option>
))}
</select>
</label>
```
- [ ] **Step 6: typecheck**
Run: `cd /root/metapi && npm run typecheck:web 2>&1 | tail -5`
Expected: 无 TS 错误。
- [ ] **Step 7: Commit**
```bash
cd /root/metapi && git add src/web/pages/DigitalHuman.tsx
git commit -m "feat(digital-human): 前端加视频工作流选择器(api_video_workflow)
Co-Authored-By: Claude <noreply@anthropic.com>"
```
<!-- T2 -->
## Task 2: BoosAPI 后端转发 api_video_workflow 给 Pixelle
**Files:**
- Modify: `src/routes/digital_human.rs`
- [ ] **Step 1: 在 pixelle_request_body 加转发(~line 2077,tts_workflow 块之后)**
找到 `pixelle_request_body` 里转发 tts_workflow 的块(约 line 2073-2078):
```rust
if let Some(value) = optional_string(body, &["ttsWorkflow", "tts_workflow"])
.or_else(|| default_pixelle_tts_workflow(state, backend_provider))
{
request_body["tts_workflow"] = json!(value);
}
```
在它**之后**插入:
```rust
if let Some(value) = optional_string(body, &["apiVideoWorkflow", "api_video_workflow"]) {
request_body["api_video_workflow"] = json!(value);
}
```
- [ ] **Step 2: 构建确认编译**
Run: `cd /root/metapi && cargo build -j 2 2>&1 | tail -3`
Expected: `Finished`。
- [ ] **Step 3: 确认 optional_string 接受多 key(它已在文件内大量使用,签名兼容)**
Run: `cd /root/metapi && rtk proxy grep -n "fn optional_string" src/routes/digital_human.rs | head`
Expected: 找到定义,签名为 `(body, keys: &[&str])`(与 Step 1 用法一致)。若签名不同,按实际调整调用形式。
- [ ] **Step 4: Commit**
```bash
cd /root/metapi && git add src/routes/digital_human.rs
git commit -m "feat(digital-human): 后端转发 api_video_workflow 给 Pixelle
Co-Authored-By: Claude <noreply@anthropic.com>"
```
<!-- T3 -->
## Task 3: Pixelle 给 comfy 视频工作流注入 audio_path
**Files:**
- Modify(容器内):`/app/pixelle_video/pipelines/asset_based.py`
- [ ] **Step 1: 定位音频注入块(~line 703)**
Run: `rtk proxy docker exec pixelle-video-api sh -lc "grep -n 'audio_driven_i2v' /app/pixelle_video/pipelines/asset_based.py"`
Expected: 命中 `if "audio_driven_i2v" in adapter_abilities:` 那行(约 703)。
- [ ] **Step 2: 在该判断旁加 comfy 前缀分支(用 python 精确改写)**
```bash
rtk proxy docker exec pixelle-video-api /app/.venv/bin/python -c "
p='/app/pixelle_video/pipelines/asset_based.py'
src=open(p).read()
anchor=' if \"audio_driven_i2v\" in adapter_abilities:\n api_video_params[\"audio_path\"] = frame.audio_path'
assert anchor in src, 'anchor not found'
add=anchor + '''
elif isinstance(api_video_workflow, str) and api_video_workflow.startswith(\"comfy/\"):
api_video_params[\"audio_path\"] = frame.audio_path'''
if 'api_video_workflow.startswith(\"comfy/\")' in src:
print('already patched')
else:
src=src.replace(anchor, add, 1)
open(p,'w').write(src)
print('patched')
"
```
Expected: `patched`(或 `already patched`)。
- [ ] **Step 3: 语法校验 + 重启 + 备份**
```bash
rtk proxy docker exec pixelle-video-api /app/.venv/bin/python -c "import ast; ast.parse(open('/app/pixelle_video/pipelines/asset_based.py').read()); print('syntax OK')"
cd /opt/Pixelle-Video && rtk proxy docker compose restart api && sleep 7 && rtk proxy docker ps --filter name=pixelle --format '{{.Names}} {{.Status}}'
mkdir -p /opt/Pixelle-Video/patches && rtk proxy docker cp pixelle-video-api:/app/pixelle_video/pipelines/asset_based.py /opt/Pixelle-Video/patches/asset_based.py.patched
```
Expected: `syntax OK`;容器 healthy;备份文件存在。
- [ ] **Step 4: 确认改动重启后仍在**
Run: `rtk proxy docker exec pixelle-video-api sh -lc "grep -c 'api_video_workflow.startswith(\"comfy/\")' /app/pixelle_video/pipelines/asset_based.py"`
Expected: `1`。无 git commit(Pixelle 非本仓库)。
<!-- T4 -->
## Task 4: 部署 BoosAPI + 端到端联调
**Files:** 无(部署 + 运行时验证)
- [ ] **Step 1: 重新构建并重启 BoosAPI(含前端改动)**
前端改了需重新 build 前端资源,后端改了需重新编译。用项目脚本:
```bash
cd /root/metapi && ./build-and-run.sh --fast-release 2>&1 | tail -15
```
> 若只想快速验证后端逻辑、前端单独 build,可 `npm run build:web` + `./build-and-run.sh --backend-only`。
> Expected: 构建成功,BoosAPI 起在 :4000。注意这是动线上服务,确认当前无关键流量再重启。
- [ ] **Step 2: 确认数字人 UI 出现「视频工作流」选择器**
打开管理控制台数字人页面,确认新增「视频工作流(可选)」下拉,选项含
`video_digital_ltx2`(comfy)+ `video_wan2.1_fusionx`(comfy)等 video_* 工作流。
- [ ] **Step 3: 发起数字人任务,视频工作流选 `comfy/video_digital_ltx2.json`**
给肖像图 + 文本 + 选 TTS,视频工作流选 `comfy/video_digital_ltx2.json`,提交。
- [ ] **Step 4: 监控流转(BoosAPI 日志 + Comfy Cloud job)**
```bash
cd /root/metapi && rtk proxy sqlite3 boosapi.db "SELECT id, created_at, client_family, http_status, substr(error_message,1,80) FROM proxy_logs ORDER BY id DESC LIMIT 5;"
```
Expected: 新日志(id 增长),数字人任务推进;Comfy Cloud 出现 LTX2.3 job;最终出说话视频。
- [ ] **Step 5: 出错归因**
- LoadImage 仍用默认图 → 查 media.py image_path 转发(Task 已完成,确认 `grep image_path /app/pixelle_video/services/media.py`)。
- LoadAudio 无音频 → 查 Task 3 注入(`grep comfy/ /app/pixelle_video/pipelines/asset_based.py`)+ workflow 标记 `$~audio_path!`。
- `api_video_workflow` 没传到 → 查 Task 2 后端转发 + Task 1 前端 payload 字段名(`api_video_workflow`)。
- 节点/模型错 → 不应发生(probe 已过);若发生看 Comfy Cloud 真实回包。
- [ ] **Step 6: 成功标准**
数字人任务选 comfy/video_digital_ltx2.json 后,Comfy Cloud 出真实 job,注入了
image_path+audio_path+prompt,返回带音频说话视频,数字人成片。
---
## 完成标准
- 前端:数字人页有「视频工作流」可选下拉,列 video_* 工作流,typecheck 干净。
- 后端:`api_video_workflow` 透传给 Pixelle,`cargo build -j 2` 通过。
- Pixelle:comfy 视频工作流注入 audio_path,重启生效,备份 patches/。
- 端到端:选 comfy/video_digital_ltx2.json 出说话视频。
- 向后兼容:不选视频工作流时,现有「图片+HTML 合成」行为不变。
## 已知风险 / 备注
- Pixelle asset_based.py 改动在镜像内置层,重建镜像会丢,已备份 patches/,长期应固化 Dockerfile。
- Task 4 动线上服务(重启 BoosAPI),确认时机。
- 单人肖像;多人不在范围。
- LTX2.3 执行时长/分辨率等真实生成参数,若出片质量/超时问题属调参,非本计划的接线问题。
docs/superpowers/plans/2026-06-18-ltx2-digital-human-workflow.md
+335
View File
@@ -0,0 +1,335 @@
# LTX2.3 数字人工作流(Comfy Cloud)实现计划
> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
**Goal:** 让 Pixelle 数字人(说话头像)走 Comfy Cloud:把官方 LTX2.3 id_lora 模板做成 `comfy/digital_ltx2.json` 工作流,补上 Pixelle media.py 的 image_path 转发缺口,经已建好的 comfy-cloud 适配器执行。
**Architecture:** 工作流文件落 Pixelle 宿主 `data/workflows/comfy/`(经 `./data` 挂载),用 comfykit 的 `_meta.title` 标记(`$~image_path!`/`$~audio_path!`/`$prompt!`)注入肖像/音频/脚本;media.py 非 api 分支补 image_path 进 workflow_params;comfy/ 通道经 `comfyui_url`(=BoosAPI `/comfy-cloud` 适配器)打到 Comfy Cloud。
**Tech Stack:** Python (Pixelle/comfykit), ComfyUI API-format JSON, Comfy Cloud API, Docker。
> **环境约定:** Pixelle 跑在 Docker 容器 `pixelle-video-api`,代码 `/app/pixelle_video/`,工作流 `/app/data/workflows/`(宿主 `/opt/Pixelle-Video/data/workflows/`,bind mount,改宿主即生效)。容器内 python:`/app/.venv/bin/python`。BoosAPI 适配端点:容器内经 `http://172.17.0.1:4000/comfy-cloud`,宿主经 `http://127.0.0.1:4000/comfy-cloud`。改 media.py 后需 `docker compose restart api`。
> **硬依赖(Task 1 阻塞全局):** 需用户从 Comfy Cloud 网页导出 `video_ltx2_3_id_lora` 的 **API 格式** JSON 到 `/tmp/ltx2_api.json`。服务端无法代取。
---
## 文件结构
- 用户提供:`/tmp/ltx2_api.json` —— Comfy Cloud 导出的 API 格式工作流(子图已展开)。
- Create `/opt/Pixelle-Video/data/workflows/comfy/digital_ltx2.json` —— 改造后的数字人工作流(加标记、删 RecordAudio)。
- Modify(容器内)`/app/pixelle_video/services/media.py` —— 非 api 分支把 image_path 加入 workflow_params;同步宿主持久化方案。
- 临时:`/tmp/digital_ltx2_probe.json` —— 校验探测用 payload。
---
<!-- TASKS -->
## Task 1: 获取并校验 API 格式导出(硬依赖)
**Files:**
- 用户提供:`/tmp/ltx2_api.json`
- [ ] **Step 1: 确认导出文件存在且是 API 格式**
用户在 Comfy Cloud 网页打开 `video_ltx2_3_id_lora`(或 share `71f221d28df8`)→ Workflow → Export (API Format) → 放到 `/tmp/ltx2_api.json`。
Run: `rtk proxy docker exec pixelle-video-api sh -lc "ls -la /tmp/ltx2_api.json 2>/dev/null || echo MISSING"`
注意:文件在宿主还是容器?用户可能放宿主 `/tmp`。两处都查:
Run(宿主): `ls -la /tmp/ltx2_api.json 2>/dev/null || echo HOST_MISSING`
Expected: 文件存在(任一处)。若两处都 MISSING → BLOCKED,等用户提供。
- [ ] **Step 2: 校验是 API 格式(不是 UI 格式)**
API 格式是 `{节点id: {class_type, inputs, ...}}`,无顶层 `nodes` 数组。
Run:
```bash
python3 -c "
import json
wf=json.load(open('/tmp/ltx2_api.json'))
is_ui = isinstance(wf,dict) and 'nodes' in wf
print('UI格式(需重导)' if is_ui else 'API格式 OK')
if not is_ui:
print('节点数:', len(wf))
has_sub = any('subgraph' in str(v.get('class_type','')).lower() for v in wf.values() if isinstance(v,dict))
print('含未展开子图?', has_sub)
"
```
Expected: `API格式 OK`,节点数 >10,无未展开子图。若是 UI 格式或含子图 → 让用户用 **API Format** 重新导出(普通 Export 是 UI 格式)。
- [ ] **Step 3: 列出节点类型 + 模型引用,核对 Comfy Cloud 兼容**
Run:
```bash
python3 -c "
import json
wf=json.load(open('/tmp/ltx2_api.json'))
from collections import Counter
c=Counter(v.get('class_type') for v in wf.values() if isinstance(v,dict))
print('节点类型:')
for t,n in c.most_common(): print(f' {n}x {t}')
print('--- 模型引用 ---')
for nid,nd in wf.items():
if not isinstance(nd,dict): continue
for k,v in (nd.get('inputs') or {}).items():
if isinstance(v,str) and v.endswith('.safetensors'):
print(f' {nid}.{k} = {v}')
"
```
Expected: 看到 LTX2.3 节点 + 模型文件名。记录下来,Task 2 核对它们在 Comfy Cloud 池里(之前已验证 ltx-2.3-* 系列在;若导出引用了不同文件名,需在此对照 `/tmp/cc_nodes.json` 的池子)。
- [ ] **Step 4: 无需提交(纯校验,无文件改动)**
本任务只确认输入就绪。无 commit。
<!-- T2 -->
## Task 2: 改造工作流(加标记 + 删 RecordAudio + 落 comfy/)
**Files:**
- Create: `/opt/Pixelle-Video/data/workflows/comfy/digital_ltx2.json`
- [ ] **Step 1: 找到要标记的节点 id(LoadImage/LoadAudio/文本/RecordAudio)**
Run:
```bash
python3 -c "
import json
wf=json.load(open('/tmp/ltx2_api.json'))
for nid,nd in wf.items():
if not isinstance(nd,dict): continue
ct=nd.get('class_type','')
if ct in ('LoadImage','LoadAudio','RecordAudio','SaveVideo','PrimitiveStringMultiline','CLIPTextEncode'):
print(nid, ct, '| inputs:', json.dumps(nd.get('inputs',{}),ensure_ascii=False)[:100])
"
```
Expected: 看到 LoadImage、LoadAudio、RecordAudio、SaveVideo、文本节点各自的 id。记下:
- LoadImage 的 id(标 `$~image_path!`)
- LoadAudio 的 id(标 `$~audio_path!`)
- 文本提示节点 id(标 `$prompt!`)—— 优先 `PrimitiveStringMultiline`;若文本经 CLIPTextEncode 的 `text` 字段直接给,则标 CLIPTextEncode
- RecordAudio 的 id(删除)
- [ ] **Step 2: 写改造脚本生成 comfy/digital_ltx2.json**
> 把下面 `IMAGE_ID`/`AUDIO_ID`/`TEXT_ID`/`RECORD_ID` 替换为 Step 1 查到的实际 id。
> 文本节点字段名:若 PrimitiveStringMultiline 用 `value` 字段,标记写 `$prompt.value!`;
> 若 CLIPTextEncode 用 `text` 字段,写 `$prompt.text!`。按 Step 1 实际字段定。
```bash
python3 -c "
import json
wf=json.load(open('/tmp/ltx2_api.json'))
IMAGE_ID='REPLACE_IMAGE_ID'
AUDIO_ID='REPLACE_AUDIO_ID'
TEXT_ID='REPLACE_TEXT_ID'
TEXT_MARKER='\$prompt.value!' # 或 \$prompt.text! 视字段而定
RECORD_ID='REPLACE_RECORD_ID' # 若无 RecordAudio 留空字符串
def set_title(nid, marker):
nd=wf[nid]
nd.setdefault('_meta',{})['title']=marker
set_title(IMAGE_ID, '\$~image_path!')
set_title(AUDIO_ID, '\$~audio_path!')
set_title(TEXT_ID, TEXT_MARKER)
# 删 RecordAudio 并清理引用它的连线(把指向它的输入置空/删除)
if RECORD_ID and RECORD_ID in wf:
wf.pop(RECORD_ID)
for nid,nd in wf.items():
if not isinstance(nd,dict): continue
for k,v in list((nd.get('inputs') or {}).items()):
if isinstance(v,list) and len(v)==2 and str(v[0])==RECORD_ID:
# 该输入原本接 RecordAudio;数字人用 LoadAudio,删除这个悬空连接
del nd['inputs'][k]
import os
os.makedirs('/opt/Pixelle-Video/data/workflows/comfy', exist_ok=True)
json.dump(wf, open('/opt/Pixelle-Video/data/workflows/comfy/digital_ltx2.json','w'), ensure_ascii=False, indent=2)
print('written, 节点数:', len(wf))
# 校验标记落位
for nid in [IMAGE_ID,AUDIO_ID,TEXT_ID]:
print(nid, '->', wf.get(nid,{}).get('_meta',{}).get('title'))
"
```
Expected: 写入成功,三个标记落位正确,RecordAudio 已删。
> ⚠️ RecordAudio 与 LoadAudio 的关系:数字人用 LoadAudio 输入旁白。若导出的图里音频源是 RecordAudio 而非 LoadAudio(录音节点直接接到音频处理),则不能简单删 RecordAudio——要把音频处理节点的输入改接到 LoadAudio。Step 1 查清音频实际从哪个节点流出;若是 RecordAudio 流出,本步改为:保留一个 LoadAudio(标 `$~audio_path!`)并把下游音频输入接到 LoadAudio 的输出。具体连接以 Step 1 的图为准。
- [ ] **Step 3: 校验生成的 JSON 合法 + comfykit 能解析出参数**
Run(容器内,用 comfykit 解析):
```bash
rtk proxy docker exec pixelle-video-api /app/.venv/bin/python -c "
import json
from comfykit.comfyui.workflow_parser import WorkflowParser
wf=json.load(open('/app/data/workflows/comfy/digital_ltx2.json'))
p=WorkflowParser()
params=[]
for nid,nd in wf.items():
if not isinstance(nd,dict): continue
pl,ml,om=p.parse_node(nid,nd)
for x in pl: params.append((x.name,x.required,x.need_upload))
print('解析出的参数:', params)
"
```
Expected: 看到 `image_path`(upload=True)、`audio_path`(upload=True)、`prompt` 三个参数。
- [ ] **Step 4: Commit(工作流文件在 Pixelle 宿主目录,非 BoosAPI 仓库——仅记录到计划备注)**
工作流文件不在 git 仓库内。无 git commit;在此记录文件已落 `/opt/Pixelle-Video/data/workflows/comfy/digital_ltx2.json`。
<!-- T3 -->
## Task 3: 补 media.py 转发 image_path 到 comfy 通道
**Files:**
- Modify(容器内):`/app/pixelle_video/services/media.py`
> 注:`pixelle_video` 源码**在镜像内置,不在挂载卷**。容器内改 `docker compose restart` 能留,
> 但 `docker compose down && up`/重建镜像会丢。持久化方案见 Step 4。
- [ ] **Step 1: 定位 workflow_params 构建处**
`media.py` 的 `__call__` 里,api/ 分支之后、`workflow_params = {"prompt": prompt}` 起的那段
(约 line 232)。`image_path` 是 `__call__` 的具名参数但没进 `workflow_params`。
Run: `rtk proxy docker exec pixelle-video-api sh -lc "grep -n 'workflow_params = {\"prompt\"' /app/pixelle_video/services/media.py"`
Expected: 定位到该行号(约 232)。
- [ ] **Step 2: 在 workflow_params 构建处加入 image_path**
在 `workflow_params = {"prompt": prompt}` 之后插入(用 sed 或 python 改文件)。注意这是容器内文件,
用 `docker exec ... python` 做精确插入最稳妥:
```bash
rtk proxy docker exec pixelle-video-api /app/.venv/bin/python -c "
p='/app/pixelle_video/services/media.py'
src=open(p).read()
anchor='workflow_params = {\"prompt\": prompt}'
assert anchor in src, 'anchor not found'
add='''workflow_params = {\"prompt\": prompt}
if image_path is not None:
workflow_params[\"image_path\"] = image_path'''
if 'workflow_params[\"image_path\"]' in src:
print('already patched')
else:
src=src.replace(anchor, add, 1)
open(p,'w').write(src)
print('patched')
"
```
Expected: `patched`(或 `already patched`)。
- [ ] **Step 3: 校验语法 + 重启容器**
```bash
rtk proxy docker exec pixelle-video-api /app/.venv/bin/python -c "import ast; ast.parse(open('/app/pixelle_video/services/media.py').read()); print('syntax OK')"
cd /opt/Pixelle-Video && rtk proxy docker compose restart api && sleep 7 && rtk proxy docker ps --filter name=pixelle --format '{{.Names}} {{.Status}}'
```
Expected: `syntax OK`;容器 `Up ... (healthy)`。
- [ ] **Step 4: 持久化方案(防镜像重建丢失)**
把改动备份到宿主,并记录到 Pixelle 部署说明:
```bash
rtk proxy docker cp pixelle-video-api:/app/pixelle_video/services/media.py /opt/Pixelle-Video/patches/media.py.patched 2>/dev/null || (mkdir -p /opt/Pixelle-Video/patches && rtk proxy docker cp pixelle-video-api:/app/pixelle_video/services/media.py /opt/Pixelle-Video/patches/media.py.patched)
echo "已备份改后 media.py 到 /opt/Pixelle-Video/patches/;重建镜像后需重新 docker cp 回 /app/pixelle_video/services/media.py 或固化进 Dockerfile"
```
Expected: 备份文件存在。无 git commit(Pixelle 非本仓库)。
<!-- T4 -->
## Task 4: 校验探测(确认 Comfy Cloud 接受工作流)
**Files:**
- 临时:`/tmp/digital_ltx2_probe.json`
- [ ] **Step 1: 用占位输入构建 probe payload**
注入标记的字段需要具体值才能提交校验。用占位文件名探测(校验在执行前,不真正读文件):
```bash
python3 -c "
import json
wf=json.load(open('/opt/Pixelle-Video/data/workflows/comfy/digital_ltx2.json'))
# probe 直接提交节点图本身(标记字段已有默认值或占位);comfykit 注入是运行时的事,
# 这里验证 Comfy Cloud 是否接受这套节点+模型
json.dump({'prompt':wf}, open('/tmp/digital_ltx2_probe.json','w'), ensure_ascii=False)
print('probe payload bytes:', len(open('/tmp/digital_ltx2_probe.json').read()))
"
```
Expected: payload 生成。
> 注:工作流里 LoadImage/LoadAudio 的默认 widget 值(模板自带的示例文件名)可能在 Comfy Cloud
> 不存在,导致校验报"文件不存在"。这是**预期且可接受**的——它证明节点+模型校验已过,只差真实输入。
> 关注点是有没有 `unsupported node type` / 模型缺失类错误。
- [ ] **Step 2: 提交探测,读校验结果**
```bash
curl -s -w "\nHTTP %{http_code}\n" -X POST http://127.0.0.1:4000/comfy-cloud/prompt -H "Content-Type: application/json" --data @/tmp/digital_ltx2_probe.json 2>&1 | head -15
```
Expected 判读:
- `{"node_errors":{},"prompt_id":"..."}` HTTP 200 → 完美,全兼容。
- `400 ... unsupported node type 'X'` → 节点 X 不在 Comfy Cloud,需在工作流里替换/移除该节点(回 Task 2 处理)。
- `400 ... 文件/模型 不存在`(针对 LoadImage 示例图或某 .safetensors)→ 若是输入文件(LoadImage 默认图)属预期;若是 .safetensors 模型缺失,需换 Comfy Cloud 有的等价模型(对照 `/tmp/cc_nodes.json` 池)。
- [ ] **Step 3: 据结果迭代或放行**
- 全兼容 → 进 Task 5。
- 节点/模型问题 → 回 Task 2 调整工作流(换节点或模型名),重跑 Task 4。不要跳过。
<!-- T5 -->
## Task 5: 真实数字人任务联调
**Files:** 无(运行时验证)
- [ ] **Step 1: 在 Pixelle 前端发起数字人任务,视频/动画工作流选 `comfy/digital_ltx2.json`**
数字人流程的 image→video 动画步(`api_video_workflow` 或对应 UI 项)填/选 `comfy/digital_ltx2.json`。
触发一个任务(给个肖像图 + 文本)。
- [ ] **Step 2: 观察任务流转**
预期:LLM 脚本步 → 生成肖像图(comfy 图片工作流)+ TTS 音频 → digital_ltx2 动画步:
注入 image_path/audio_path/prompt → Comfy Cloud 建 job → 轮询 completed → 取回说话视频 → HTML 合成。
监控 BoosAPI 侧 proxy_logs:
```bash
rtk proxy sqlite3 boosapi.db "SELECT id, created_at, client_family, http_status, substr(error_message,1,80) FROM proxy_logs ORDER BY id DESC LIMIT 5;"
```
Expected: 新日志(id 增长),数字人任务最终 success / 出片。
- [ ] **Step 3: 出错则按错误类型归因**
- `unsupported node` / 模型缺失 → 回 Task 2/4。
- image_path 未注入(LoadImage 仍用默认图)→ 回 Task 3 确认 media.py 改动生效(`grep image_path /app/.../media.py`)+ Task 2 确认 `$~image_path!` 标记落位。
- 执行期失败(Comfy Cloud job failed)→ 真实生成问题(参数/分辨率/时长),据 job 错误调工作流默认值。
- [ ] **Step 4: 成功标准**
数字人任务在 Comfy Cloud 出现真实 job、跑完、返回带音频的说话视频,Pixelle 合成出片。
---
## 完成标准
- `comfy/digital_ltx2.json` 落地、comfykit 能解析出 image_path/audio_path/prompt 三参数。
- media.py 已转发 image_path 到 comfy 通道(并备份到宿主 patches/)。
- 校验探测确认 Comfy Cloud 接受工作流(节点+模型兼容)。
- 真实数字人任务经 comfy/Comfy Cloud 出片。
## 已知风险 / 备注
- 硬依赖用户导出 API JSON(Task 1);拿不到则全卡。
- media.py 改动在镜像内置层,重建镜像会丢,已备份到 `/opt/Pixelle-Video/patches/`,长期应固化进 Dockerfile/启动脚本。
- 工作流默认 widget 值(示例图/音频文件名)在 Comfy Cloud 不存在属正常,真实运行靠注入覆盖。
- 单人肖像;多人对话不在范围。
docs/superpowers/plans/2026-06-18-pixelle-connection-management.md
+503
View File
@@ -0,0 +1,503 @@
# Pixelle 连接凭证纳入 BoosAPI 管理 实现计划
> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
**Goal:** 在 BoosAPI 连接管理页加「Pixelle 连接」卡片,管 runninghub_api_key / comfyui_url / comfyui_api_key 三个凭证,保存即写入 settings 表 + 同步 Pixelle config.yaml + 重启 pixelle 容器生效。
**Architecture:** 新增 service `pixelle_connection.rs`(读写 settings 表 + 改 config.yaml YAML 三键 + docker restart)+ admin 路由(GET/PUT,密钥掩码)+ 前端 Accounts 页卡片。settings 表为真相源,config.yaml 是同步目标。
**Tech Stack:** Rust(axum, sqlx, serde_yaml<新增依赖>, tokio::process)、React/TS。
> **构建/测试:** `cargo build -j 2`(-j2 防 OOM)、`cargo test -p boosapi --lib pixelle_connection`、`npm run typecheck:web`。分支 `feat/comfy-cloud-adapter`。Pixelle compose 目录 `/opt/Pixelle-Video`,config `/opt/Pixelle-Video/config.yaml`。
---
## 文件结构
- Modify `Cargo.toml` — 加 `serde_yaml` 依赖。
- Modify `src/config.rs` — `PixelleVideoConfig` 加 `config_path` / `compose_dir` 两字段(默认 `/opt/Pixelle-Video/config.yaml`、`/opt/Pixelle-Video`)。
- Create `src/services/pixelle_connection.rs` — read/save settings + sync_to_pixelle(改 yaml)+ restart。
- Modify `src/services/mod.rs` — `pub mod pixelle_connection;`。
- Create `src/routes/admin/pixelle_connection.rs` — GET/PUT handler(掩码)。
- Modify `src/routes/admin/mod.rs` — 声明子模块 + 挂 2 条路由。
- Modify `src/web/api.ts` — adminApi 加 getPixelleConnection / savePixelleConnection。
- Modify `src/web/pages/Accounts.tsx` — 加「Pixelle 连接」卡片。
---
<!-- TASKS -->
## Task 1: 加 serde_yaml 依赖 + config 路径字段
**Files:**
- Modify: `Cargo.toml`
- Modify: `src/config.rs`
- [ ] **Step 1: Cargo.toml 加 serde_yaml**
在 `[dependencies]` 段加(版本对齐项目 serde 生态,用 0.9):
```toml
serde_yaml = "0.9"
```
- [ ] **Step 2: PixelleVideoConfig 加两字段(src/config.rs,struct 内 timeout_secs 后)**
在 `pub timeout_secs: u64,` 之后加:
```rust
#[serde(default = "default_pixelle_config_path")]
pub config_path: String,
#[serde(default = "default_pixelle_compose_dir")]
pub compose_dir: String,
```
- [ ] **Step 3: 加默认值函数(src/config.rs,default_pixelle_backend_provider 附近)**
```rust
fn default_pixelle_config_path() -> String {
"/opt/Pixelle-Video/config.yaml".to_string()
}
fn default_pixelle_compose_dir() -> String {
"/opt/Pixelle-Video".to_string()
}
```
- [ ] **Step 4: PixelleVideoConfig::default() 补两字段**
找到 `impl Default for ...` 或 `PixelleVideoConfig::default()`(约 line 207 区域,有 `api_base_url: Some(...)` 那个),在其字段列表末尾加:
```rust
config_path: default_pixelle_config_path(),
compose_dir: default_pixelle_compose_dir(),
```
- [ ] **Step 5: 构建确认**
Run: `cd /root/metapi && cargo build -j 2 2>&1 | tail -3`
Expected: `Finished`。
- [ ] **Step 6: Commit**
```bash
cd /root/metapi && git add Cargo.toml Cargo.lock src/config.rs
git commit -m "feat(pixelle): 加 serde_yaml + Pixelle config 路径配置项
Co-Authored-By: Claude <noreply@anthropic.com>"
```
<!-- T2 -->
## Task 2: pixelle_connection service(settings + yaml 同步)
**Files:**
- Create: `src/services/pixelle_connection.rs`
- Modify: `src/services/mod.rs`
- [ ] **Step 1: src/services/mod.rs 加模块声明**
```rust
pub mod pixelle_connection;
```
- [ ] **Step 2: 写失败测试 `src/services/pixelle_connection.rs`(含结构 + sync 测试)**
```rust
use crate::error::{AppError, AppResult};
use serde::{Deserialize, Serialize};
use sqlx::SqlitePool;
#[derive(Debug, Clone, Default, Serialize, Deserialize)]
#[serde(rename_all = "camelCase")]
pub struct PixelleConnection {
pub runninghub_api_key: Option<String>,
pub comfyui_url: Option<String>,
pub comfyui_api_key: Option<String>,
}
const KEY_RH: &str = "pixelle.runninghub_api_key";
const KEY_URL: &str = "pixelle.comfyui_url";
const KEY_CK: &str = "pixelle.comfyui_api_key";
pub async fn read_connection(db: &SqlitePool) -> AppResult<PixelleConnection> {
async fn get(db: &SqlitePool, k: &str) -> AppResult<Option<String>> {
Ok(sqlx::query_scalar("SELECT value FROM settings WHERE key = ?")
.bind(k).fetch_optional(db).await?)
}
Ok(PixelleConnection {
runninghub_api_key: get(db, KEY_RH).await?,
comfyui_url: get(db, KEY_URL).await?,
comfyui_api_key: get(db, KEY_CK).await?,
})
}
pub async fn save_connection(db: &SqlitePool, conn: &PixelleConnection) -> AppResult<()> {
async fn put(db: &SqlitePool, k: &str, v: &Option<String>) -> AppResult<()> {
if let Some(val) = v {
sqlx::query("INSERT OR REPLACE INTO settings (key, value) VALUES (?, ?)")
.bind(k).bind(val).execute(db).await?;
}
Ok(())
}
put(db, KEY_RH, &conn.runninghub_api_key).await?;
put(db, KEY_URL, &conn.comfyui_url).await?;
put(db, KEY_CK, &conn.comfyui_api_key).await?;
Ok(())
}
/// 改 config.yaml 的 comfyui.{runninghub_api_key,comfyui_url,comfyui_api_key} 三键,其余保留。
/// 改前备份到 <path>.bak-<ts>。返回备份路径。
pub fn sync_to_pixelle(config_path: &str, conn: &PixelleConnection) -> AppResult<String> {
let content = std::fs::read_to_string(config_path)
.map_err(|e| AppError::ServiceUnavailable(format!("读取 Pixelle config 失败: {e}")))?;
let mut doc: serde_yaml::Value = serde_yaml::from_str(&content)
.map_err(|e| AppError::ServiceUnavailable(format!("解析 config.yaml 失败: {e}")))?;
let comfyui = doc.get_mut("comfyui")
.ok_or_else(|| AppError::ServiceUnavailable("config.yaml 缺少 comfyui 段".into()))?;
let map = comfyui.as_mapping_mut()
.ok_or_else(|| AppError::ServiceUnavailable("comfyui 段不是映射".into()))?;
if let Some(v) = &conn.runninghub_api_key {
map.insert("runninghub_api_key".into(), serde_yaml::Value::String(v.clone()));
}
if let Some(v) = &conn.comfyui_url {
map.insert("comfyui_url".into(), serde_yaml::Value::String(v.clone()));
}
if let Some(v) = &conn.comfyui_api_key {
map.insert("comfyui_api_key".into(), serde_yaml::Value::String(v.clone()));
}
let ts = chrono::Utc::now().format("%Y%m%d%H%M%S").to_string();
let backup = format!("{config_path}.bak-{ts}");
std::fs::copy(config_path, &backup)
.map_err(|e| AppError::ServiceUnavailable(format!("备份失败: {e}")))?;
let out = serde_yaml::to_string(&doc)
.map_err(|e| AppError::Internal(anyhow::anyhow!(e)))?;
std::fs::write(config_path, out)
.map_err(|e| AppError::ServiceUnavailable(format!("写入 config 失败: {e}")))?;
Ok(backup)
}
#[cfg(test)]
mod tests {
use super::*;
#[test]
fn sync_updates_three_keys_preserves_rest() {
let dir = std::env::temp_dir().join(format!("pxtest_{}", uuid::Uuid::new_v4().simple()));
std::fs::create_dir_all(&dir).unwrap();
let path = dir.join("config.yaml");
std::fs::write(&path,
"project_name: Pixelle-Video\ncomfyui:\n comfyui_url: https://old\n runninghub_api_key: oldkey\n comfyui_api_key: oldck\n runninghub_concurrent_limit: 1\n").unwrap();
let conn = PixelleConnection {
runninghub_api_key: Some("newkey".into()),
comfyui_url: Some("http://new".into()),
comfyui_api_key: Some("newck".into()),
};
let backup = sync_to_pixelle(path.to_str().unwrap(), &conn).unwrap();
assert!(std::path::Path::new(&backup).exists());
let after = std::fs::read_to_string(&path).unwrap();
assert!(after.contains("newkey"));
assert!(after.contains("http://new"));
assert!(after.contains("newck"));
// 保留其余键
assert!(after.contains("runninghub_concurrent_limit"));
assert!(after.contains("project_name"));
std::fs::remove_dir_all(&dir).ok();
}
}
```
- [ ] **Step 3: 运行测试,确认失败**
Run: `cd /root/metapi && cargo test -p boosapi --lib services::pixelle_connection 2>&1 | tail -15`
Expected: FAIL —— 模块/函数未定义(首次编译错误)。
- [ ] **Step 4: 实现**
Step 2 的代码即实现(测试与实现同文件)。确保 mod.rs 已声明。
- [ ] **Step 5: 运行测试,确认通过**
Run: `cd /root/metapi && cargo test -p boosapi --lib services::pixelle_connection 2>&1 | tail -10`
Expected: PASS(1 个测试)。
- [ ] **Step 6: Commit**
```bash
cd /root/metapi && git add src/services/mod.rs src/services/pixelle_connection.rs
git commit -m "feat(pixelle): 连接凭证 service(settings 读写 + config.yaml 同步)
Co-Authored-By: Claude <noreply@anthropic.com>"
```
<!-- T3 -->
## Task 3: restart helper + admin 路由(掩码)
**Files:**
- Modify: `src/services/pixelle_connection.rs`(加 restart)
- Create: `src/routes/admin/pixelle_connection.rs`
- Modify: `src/routes/admin/mod.rs`
- [ ] **Step 1: 加 restart_pixelle(pixelle_connection.rs,sync_to_pixelle 之后)**
```rust
pub async fn restart_pixelle(compose_dir: &str) -> AppResult<()> {
let output = tokio::process::Command::new("docker")
.args(["compose", "restart", "api"])
.current_dir(compose_dir)
.output()
.await
.map_err(|e| AppError::ServiceUnavailable(format!("docker compose restart 启动失败: {e}")))?;
if !output.status.success() {
let stderr = String::from_utf8_lossy(&output.stderr);
return Err(AppError::ServiceUnavailable(format!(
"Pixelle 重启失败: {}", stderr.trim()
)));
}
Ok(())
}
```
- [ ] **Step 2: 写 admin 路由 `src/routes/admin/pixelle_connection.rs`**
```rust
use crate::error::AppResult;
use crate::services::pixelle_connection::{self, PixelleConnection};
use crate::AppState;
use axum::{extract::State, Json};
use serde::Deserialize;
use serde_json::{json, Value};
const MASK_SENTINEL: &str = "••••";
fn mask(v: &Option<String>) -> Value {
match v {
Some(s) if s.len() > 4 => json!(format!("{}{}", MASK_SENTINEL, &s[s.len()-4..])),
Some(s) if !s.is_empty() => json!(MASK_SENTINEL),
_ => Value::Null,
}
}
pub async fn get_connection(State(state): State<AppState>) -> AppResult<Json<Value>> {
let c = pixelle_connection::read_connection(&state.db).await?;
Ok(Json(json!({
"success": true,
"connection": {
// url 不算敏感,明文回;两个 key 掩码
"comfyuiUrl": c.comfyui_url,
"runninghubApiKey": mask(&c.runninghub_api_key),
"comfyuiApiKey": mask(&c.comfyui_api_key),
}
})))
}
#[derive(Debug, Deserialize)]
#[serde(rename_all = "camelCase")]
pub struct UpdatePayload {
runninghub_api_key: Option<String>,
comfyui_url: Option<String>,
comfyui_api_key: Option<String>,
}
fn keep_if_not_mask(incoming: Option<String>) -> Option<String> {
// 掩码值(以 •••• 开头)表示"未修改",跳过
match incoming {
Some(s) if s.starts_with(MASK_SENTINEL) => None,
other => other,
}
}
pub async fn put_connection(
State(state): State<AppState>,
Json(p): Json<UpdatePayload>,
) -> AppResult<Json<Value>> {
let conn = PixelleConnection {
runninghub_api_key: keep_if_not_mask(p.runninghub_api_key),
comfyui_url: p.comfyui_url, // url 明文,不掩码
comfyui_api_key: keep_if_not_mask(p.comfyui_api_key),
};
pixelle_connection::save_connection(&state.db, &conn).await?;
let backup = pixelle_connection::sync_to_pixelle(&state.config.pixelle_video.config_path, &conn)?;
let restart = pixelle_connection::restart_pixelle(&state.config.pixelle_video.compose_dir).await;
match restart {
Ok(()) => Ok(Json(json!({ "success": true, "backup": backup, "restarted": true }))),
Err(e) => Ok(Json(json!({
"success": true, "backup": backup, "restarted": false,
"warning": format!("配置已写入,但 Pixelle 重启失败,请手动重启: {e}")
}))),
}
}
```
- [ ] **Step 3: src/routes/admin/mod.rs 声明子模块 + 挂路由**
模块声明区(`mod users;` 附近)加:
```rust
mod pixelle_connection;
```
在 `routes()` 的路由链里(`/api/admin/user-balances` 那一带)加:
```rust
.route(
"/api/admin/pixelle/connection",
get(pixelle_connection::get_connection).put(pixelle_connection::put_connection),
)
```
确认 `get`/`put` 已从 axum::routing 引入(文件顶部应已 `use axum::routing::{get, post, ...}`;若缺 put 则补)。
- [ ] **Step 4: 构建确认**
Run: `cd /root/metapi && cargo build -j 2 2>&1 | tail -3`
Expected: `Finished`。
- [ ] **Step 5: Commit**
```bash
cd /root/metapi && git add src/services/pixelle_connection.rs src/routes/admin/pixelle_connection.rs src/routes/admin/mod.rs
git commit -m "feat(pixelle): 连接凭证 admin 端点(GET/PUT 掩码 + 重启)
Co-Authored-By: Claude <noreply@anthropic.com>"
```
<!-- T4 -->
## Task 4: 前端连接管理卡片
**Files:**
- Modify: `src/web/api.ts`
- Modify: `src/web/pages/Accounts.tsx`
- [ ] **Step 1: api.ts adminApi 加方法**
在 adminApi 对象里(找 `request(` 范式的 admin 方法群)加:
```typescript
getPixelleConnection: () =>
request<{ success: boolean; connection: { comfyuiUrl?: string | null; runninghubApiKey?: string | null; comfyuiApiKey?: string | null } }>("/api/admin/pixelle/connection"),
savePixelleConnection: (data: { runninghubApiKey?: string; comfyuiUrl?: string; comfyuiApiKey?: string }) =>
request<{ success: boolean; backup?: string; restarted?: boolean; warning?: string }>("/api/admin/pixelle/connection", {
method: "PUT",
body: JSON.stringify(data),
}),
```
- [ ] **Step 2: Accounts.tsx 加「Pixelle 连接」卡片**
先读 `src/web/pages/Accounts.tsx` 顶部,确认 `api`/`adminApi` 的导入名和 toast 用法。在页面主体某处(如页尾)加一个卡片组件块。最小实现(state + 加载 + 保存):
```tsx
// —— Pixelle 连接(加在组件内 state 区)——
const [pxConn, setPxConn] = useState({ comfyuiUrl: '', runninghubApiKey: '', comfyuiApiKey: '' });
const [pxSaving, setPxSaving] = useState(false);
useEffect(() => {
adminApi.getPixelleConnection()
.then((r) => setPxConn({
comfyuiUrl: r.connection?.comfyuiUrl || '',
runninghubApiKey: r.connection?.runninghubApiKey || '',
comfyuiApiKey: r.connection?.comfyuiApiKey || '',
}))
.catch(() => {});
}, []);
const savePxConn = async () => {
setPxSaving(true);
try {
const res = await adminApi.savePixelleConnection({
runninghubApiKey: pxConn.runninghubApiKey || undefined,
comfyuiUrl: pxConn.comfyuiUrl || undefined,
comfyuiApiKey: pxConn.comfyuiApiKey || undefined,
});
if (res.warning) toast.error(res.warning);
else toast.success('已保存并重启 Pixelle,约数秒生效');
} catch (e: any) {
toast.error(e?.message || '保存失败');
} finally {
setPxSaving(false);
}
};
```
卡片 JSX(加到 return 的合适位置,样式对齐页面现有 card):
```tsx
<div className="card" style={{ marginTop: 16, padding: 16 }}>
<h3>Pixelle 连接</h3>
<label style={{ display: 'block', marginBottom: 8 }}>
<span>ComfyUI URL</span>
<input value={pxConn.comfyuiUrl} onChange={(e) => setPxConn((s) => ({ ...s, comfyuiUrl: e.target.value }))} placeholder="http://172.17.0.1:4000/comfy-cloud" style={{ width: '100%' }} />
</label>
<label style={{ display: 'block', marginBottom: 8 }}>
<span>RunningHub API Key</span>
<input value={pxConn.runninghubApiKey} onChange={(e) => setPxConn((s) => ({ ...s, runninghubApiKey: e.target.value }))} placeholder="留空••••表示不改" style={{ width: '100%' }} />
</label>
<label style={{ display: 'block', marginBottom: 8 }}>
<span>Comfy Cloud API Key</span>
<input value={pxConn.comfyuiApiKey} onChange={(e) => setPxConn((s) => ({ ...s, comfyuiApiKey: e.target.value }))} placeholder="留空••••表示不改" style={{ width: '100%' }} />
</label>
<button type="button" className="btn btn-primary" disabled={pxSaving} onClick={savePxConn}>
{pxSaving ? '保存中...' : '保存并重启 Pixelle'}
</button>
</div>
```
> 注:`useState`/`useEffect` 若未导入需补;`adminApi`/`api` 用 Accounts.tsx 实际的导入名(读文件确认是 `api` 还是 `adminApi`)。若提交掩码值(`••••...`)后端会跳过不改,符合预期。
- [ ] **Step 3: typecheck**
Run: `cd /root/metapi && npm run typecheck:web 2>&1 | tail -5`
Expected: 无 TS 错误。
- [ ] **Step 4: Commit**
```bash
cd /root/metapi && git add src/web/api.ts src/web/pages/Accounts.tsx
git commit -m "feat(pixelle): 连接管理页加 Pixelle 连接卡片
Co-Authored-By: Claude <noreply@anthropic.com>"
```
<!-- T5 -->
## Task 5: 部署 + 端到端验证
**Files:** 无(部署 + 运行时)
- [ ] **Step 1: 重建并重启 BoosAPI(含前后端改动)**
```bash
cd /root/metapi && ./build-and-run.sh --fast-release 2>&1 | tail -15
```
Expected: 构建成功,BoosAPI 起在 :4000。动线上服务,确认时机。
- [ ] **Step 2: 连接管理页确认「Pixelle 连接」卡片**
硬刷新管理控制台连接管理页(`/accounts`),确认出现「Pixelle 连接」卡片,
ComfyUI URL 显示当前值,两个 key 显示掩码(`••••xxxx`)。
- [ ] **Step 3: 改一个值测试同步**
把 RunningHub API Key 改成一个新值,保存。确认:
```bash
grep runninghub_api_key /opt/Pixelle-Video/config.yaml | sed 's/[a-f0-9]\{20\}/.../'
ls -t /opt/Pixelle-Video/config.yaml.bak-* | head -1
rtk proxy docker ps --filter name=pixelle --format '{{.Names}} {{.Status}}'
```
Expected: config.yaml 的 key 变成新值;有新备份文件;容器重启后 healthy。
- [ ] **Step 4: 掩码不改测试**
只改 ComfyUI URL、两个 key 保持掩码原值,保存。确认 config.yaml 里两个 key **没变**
(掩码值被后端跳过),URL 变了。
- [ ] **Step 5: 成功标准**
UI 改 Pixelle 凭证 → settings 表存值 + config.yaml 同步 + 容器重启,不再需要手动编辑文件。
---
## 完成标准
- 后端:pixelle_connection service(读写 settings + sync_to_pixelle + restart)+ admin GET/PUT 端点,`cargo build -j 2` 通过,service 单测通过。
- 前端:连接管理页有「Pixelle 连接」卡片,typecheck 干净。
- 端到端:UI 改凭证 → config.yaml 同步 + 容器重启生效;掩码值不误改。
- 向后兼容:不改 Pixelle 源码;config.yaml 其余键保留;每次改前备份。
## 已知风险 / 备注
- serde_yaml 重序列化会丢 config.yaml 注释(已接受;每次有时间戳备份兜底)。
- BoosAPI 进程需有 docker compose 执行权限 + config.yaml 读写权限(同宿主 root 运行,满足)。
- Task 5 重启 BoosAPI 动线上服务,确认时机。
- 备份文件会累积(config.yaml.bak-*),长期可加清理,本期不做。
docs/superpowers/plans/2026-06-18-workflow-ui-split.md
+244
View File
@@ -0,0 +1,244 @@
# workflow_ui.rs 拆分(8 子模块)实现计划
> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
**Goal:** 把 `src/routes/workflow_ui.rs`(6181 行)按职责拆成 `src/routes/workflow_ui/` 目录 8 个子模块,纯机械移动、零逻辑改动,对外接口不变。
**Architecture:** 先建目录把原文件变 `mod.rs`,再逐个子模块把相关函数剪切出去(`pub(super)` 可见性 + 补 use),每步 cargo 编译验证。Rust 编译器是主安全网。
**Tech Stack:** Rust (axum, sqlx)。验证:`cargo build -j 2`、`cargo test -p boosapi --lib routes::workflow_ui`。
> **核心纪律:** 纯搬运,函数体一字不改;只改可见性 + use 路径。不优化、不改逻辑、不动路由路径。每抽完一组即编译+测试+提交。分支 `feat/comfy-cloud-adapter`。
> **验证基线(开工前先记录):** 跑 `cargo test -p boosapi --lib routes::workflow_ui 2>&1 | grep "test result"` 记下当前测试数(应 5 个),全程不得减少。
---
## 文件结构(目标)
```
src/routes/workflow_ui/
mod.rs — routes() + 共享类型(WorkflowCaller/各 Query/Payload struct)+ 跨模块小工具 + 子模块声明 + 测试入口
assets.rs — UI 静态资源服务/嵌入目录/index/static/serve_file/官方模板资源
auth.rs — caller 解析
node_defs.rs — 节点定义 + 工作流模板图
models.rs — 模型分类 + folder 模型
comfy_proxy.rs — ComfyUI API 代理 handler(settings/userdata/object_info/...)
validate.rs — 工作流校验
queue.rs — 队列/历史/prompt/view
```
> 当前 `src/routes/workflow_ui.rs`(单文件)→ 变为 `src/routes/workflow_ui/mod.rs` + 7 个兄弟文件。
> `src/routes/mod.rs` 的 `mod workflow_ui;` 声明无需改(目录模块同名,Rust 自动找 mod.rs)。
---
<!-- TASKS -->
## Task 0: 文件转目录模块(零拆分,先搭壳)
**Files:**
- Move: `src/routes/workflow_ui.rs` → `src/routes/workflow_ui/mod.rs`
- [ ] **Step 1: 记录验证基线**
Run: `cd /root/metapi && cargo test -p boosapi --lib routes::workflow_ui 2>&1 | grep "test result"`
Expected: 记下测试数(预期 `5 passed`)。后续每步此数不得减少。
- [ ] **Step 2: 把文件移成目录模块**
```bash
cd /root/metapi
mkdir -p src/routes/workflow_ui
git mv src/routes/workflow_ui.rs src/routes/workflow_ui/mod.rs
```
- [ ] **Step 3: 编译 + 测试验证(内容没动,应原样通过)**
Run: `cd /root/metapi && cargo build -j 2 2>&1 | tail -3 && cargo test -p boosapi --lib routes::workflow_ui 2>&1 | grep "test result"`
Expected: `Finished`;测试数与基线一致。
- [ ] **Step 4: Commit**
```bash
cd /root/metapi && git add src/routes/workflow_ui.rs src/routes/workflow_ui/mod.rs
git commit -m "refactor(workflow_ui): 文件转目录模块(mod.rs,内容不变)
Co-Authored-By: Claude <noreply@anthropic.com>"
```
<!-- T1 -->
## Task 1: 抽 auth.rs(最小、最低风险,先验证流程)
**Files:**
- Create: `src/routes/workflow_ui/auth.rs`
- Modify: `src/routes/workflow_ui/mod.rs`
要搬的函数(用 grep 定位,函数体一字不改):`caller_from_headers`、`auth_caller`、`caller_user_id`、`caller_is_admin`。它们依赖类型 `WorkflowCaller`(留在 mod.rs)。
- [ ] **Step 1: 在 mod.rs 顶部加子模块声明**
在 mod.rs 的 `use` 区之后(`pub fn routes()` 之前)加:
```rust
mod auth;
```
- [ ] **Step 2: 确认这 4 个函数的精确范围 + WorkflowCaller 可见性**
Run: `cd /root/metapi && rtk proxy grep -nE "fn caller_from_headers|fn auth_caller|fn caller_user_id|fn caller_is_admin|enum WorkflowCaller" src/routes/workflow_ui/mod.rs`
记录每个函数起止行。`WorkflowCaller` 留 mod.rs,改成 `pub(super) enum WorkflowCaller`(让子模块可用)。
- [ ] **Step 3: 新建 auth.rs,粘入 4 个函数(函数体不改,补 use + 改可见性)**
新建 `src/routes/workflow_ui/auth.rs`,结构:
```rust
use super::WorkflowCaller;
use crate::error::AppResult;
use crate::AppState;
use axum::http::HeaderMap;
// (按 4 个函数实际用到的依赖补齐 use:validate_jwt、find_downstream_key_by_token 等——
// 从 mod.rs 顶部现有 use 里照抄它们需要的那几条)
pub(super) fn caller_from_headers(state: &AppState, headers: &HeaderMap) -> AppResult<WorkflowCaller> {
// ←原函数体一字不改粘进来
}
pub(super) fn caller_user_id(caller: &WorkflowCaller) -> Option<i64> {
// ←原体
}
pub(super) fn caller_is_admin(caller: &WorkflowCaller) -> bool {
// ←原体
}
pub(super) async fn auth_caller(state: &AppState, headers: &HeaderMap) -> AppResult<WorkflowCaller> {
// ←原体
}
```
> 关键:这 4 个函数从 mod.rs **删除**;其在 mod.rs/其他子模块的调用点改成 `auth::caller_from_headers(...)` 等(mod.rs 内加 `use auth::{caller_from_headers, auth_caller, caller_user_id, caller_is_admin};` 即可不改调用点写法)。
- [ ] **Step 4: mod.rs 加 use 引回,删除原 4 函数**
mod.rs 顶部子模块声明后加:
```rust
use auth::{auth_caller, caller_from_headers, caller_is_admin, caller_user_id};
```
并从 mod.rs 删掉这 4 个函数的原定义。
- [ ] **Step 5: 编译 + 测试**
Run: `cd /root/metapi && cargo build -j 2 2>&1 | tail -3 && cargo test -p boosapi --lib routes::workflow_ui 2>&1 | grep "test result"`
Expected: `Finished`;测试数 == 基线。若编译报「未使用的 use」「私有」「未解析」,按提示补 use / 调可见性(纯机械修),不改逻辑。
- [ ] **Step 6: Commit**
```bash
cd /root/metapi && git add src/routes/workflow_ui/mod.rs src/routes/workflow_ui/auth.rs
git commit -m "refactor(workflow_ui): 抽出 auth 子模块
Co-Authored-By: Claude <noreply@anthropic.com>"
```
<!-- T2 -->
## 通用抽取流程(每个子模块任务都按这 6 步)
每个抽取任务对一组函数执行:
1. mod.rs 顶部加 `mod <name>;` 声明。
2. grep 定位本组函数精确范围;凡被本组函数引用、但定义留在别处的类型/函数,把那些定义改 `pub(super)`。
3. 新建 `<name>.rs`,粘入本组函数(**函数体一字不改**),顶部按实际依赖补 `use`(从 mod.rs 现有 use 照抄需要的;跨模块的用 `use super::...` 或 `use super::<other_mod>::...`),函数可见性改 `pub(super)`。
4. 从 mod.rs 删掉这些函数原定义;mod.rs 顶部加 `use <name>::{...};` 把它们引回(调用点写法不变)。
5. `cargo build -j 2` + `cargo test -p boosapi --lib routes::workflow_ui`。编译报错按提示机械修(补 use / 调可见性),不改逻辑。测试数不得低于基线。
6. 提交:`git add src/routes/workflow_ui/mod.rs src/routes/workflow_ui/<name>.rs && git commit -m "refactor(workflow_ui): 抽出 <name> 子模块"`(带 Co-Authored-By)。
> 注:若某函数同时被多个子模块用,保留在 mod.rs 顶层并 `pub(super)`,各子模块 `use super::该函数`。
> 共用小工具(guess_mime_from_path / parse_boolish / safe_view_path / user_home / default_history_limit
> / workspace_kind_from_mime)统一留 mod.rs 顶层 `pub(super)`,不下沉到子模块。
## Task 2: 抽 node_defs.rs(节点定义 + 工作流模板图)
**Files:** Create `src/routes/workflow_ui/node_defs.rs`;Modify `src/routes/workflow_ui/mod.rs`
要搬的函数(grep 定位):`known_output_ports`、`core_node_definitions`、`workflow_template_payload`、`core_workflow_template_index`、`inject_boosapi_workflow_template_payload`、`default_boosapi_workflow_graph`、`text_to_video_workflow_graph`、`port_name`、`source_node_type`、`normalize_prompt_payload`、`prompt_link`、`node_type_def_to_comfy`、`input_spec_to_comfy`、`output_specs`、`output_is_list_specs`。
- [ ] **Step 1-6: 按「通用抽取流程」执行**,`<name>` = `node_defs`。
注意:这些函数用到 `WorkflowGraph` / `NodeTypeDefinition` 类型——确认它们的定义位置(可能在 crate::workflow 或 mod.rs),mod.rs 内的留存定义改 `pub(super)`,node_defs.rs 用 `use super::...` 或 `use crate::...` 引入。
验证命令:`cd /root/metapi && cargo build -j 2 2>&1 | tail -3 && cargo test -p boosapi --lib routes::workflow_ui 2>&1 | grep "test result"`,期望 Finished + 测试数≥基线。
提交 message:`refactor(workflow_ui): 抽出 node_defs 子模块`。
<!-- T3 -->
## Task 3: 抽 models.rs(模型分类 + folder 模型)
**Files:** Create `src/routes/workflow_ui/models.rs`;Modify `src/routes/workflow_ui/mod.rs`
要搬的函数:`is_exact_workflow_model`、`is_image_workflow_model`、`is_video_workflow_model`、`is_audio_workflow_model`、`is_embedding_workflow_model`、`is_3d_workflow_model`、`is_vision_workflow_model`、`is_chat_workflow_model`、`workflow_route_models`、`image_model_choices`、`workflow_folder_models`、`workflow_folder_is_api_only`、`workflow_folder_has_route_models`、`workflow_folder_route_model_items`、`combo_choices_from_node_input`、`combo_fields_from_node`、`native_folder_models_from_object_info`。
- [ ] **Step 1-6: 按「通用抽取流程」执行**,`<name>` = `models`。
注意:`workflow_route_models` 是 `async fn` 且用 `state.db`,补 `use crate::AppState;` 等。
验证命令同上,提交 message:`refactor(workflow_ui): 抽出 models 子模块`。
<!-- T4 -->
## Task 4: 抽 assets.rs(UI 静态资源服务)
**Files:** Create `src/routes/workflow_ui/assets.rs`;Modify `src/routes/workflow_ui/mod.rs`
要搬的函数:`workflow_ui_root_for_config`、`resolve_workflow_ui_dir`、`embedded_workflow_ui_for_config`、`workflow_ui_dir_is_usable`、`embedded_workflow_ui_is_usable`、`workflow_ui_index_is_placeholder`、`workflow_ui_runtime`、`workflow_ui_build_metadata`、`workflow_cloud_api_key`、`workflow_ui_index`、`workflow_ui_static`、`official_workflow_template_asset`、`serve_file`。
- [ ] **Step 1-6: 按「通用抽取流程」执行**,`<name>` = `assets`。
注意:用到 `include_dir::Dir`、`PathBuf`、`Html`、`Response` 等,按实际补 use。`serve_file` 若被 queue/view 模块也用到,则保留 mod.rs 顶层 `pub(super)`(实现时看引用)。
验证命令同上,提交 message:`refactor(workflow_ui): 抽出 assets 子模块`。
<!-- T5 -->
## Task 5: 抽 comfy_proxy.rs(ComfyUI API 代理 handler)
**Files:** Create `src/routes/workflow_ui/comfy_proxy.rs`;Modify `src/routes/workflow_ui/mod.rs`
要搬的函数:`get_user_config`、`create_user`、`get_settings`、`get_setting`、`store_settings`、`store_setting`、`userdata_list`、`userdata_get`、`userdata_store`、`userdata_delete`、`move_userdata`、`extensions`、`workflow_templates`、`embeddings`、`object_info`、`system_stats`。
- [ ] **Step 1-6: 按「通用抽取流程」执行**,`<name>` = `comfy_proxy`。
注意:这些是路由 handler(多 `async fn ...(State, HeaderMap) -> AppResult<...>`),依赖 `auth_caller`(已在 auth.rs)→ 用 `use super::auth_caller;` 或 `super::auth::auth_caller`。补 axum extract / Json / Response use。
验证命令同上,提交 message:`refactor(workflow_ui): 抽出 comfy_proxy 子模块`。
<!-- T6 -->
## Task 6: 抽 validate.rs(工作流校验)
**Files:** Create `src/routes/workflow_ui/validate.rs`;Modify `src/routes/workflow_ui/mod.rs`
要搬的函数:`validate_workflow`、`validate_workflow_against_object_info`、`validate_workflow_input_file`。
- [ ] **Step 1-6: 按「通用抽取流程」执行**,`<name>` = `validate`。
注意:依赖 node_defs/models 的函数(如 normalize_prompt_payload、combo_fields_from_node)→ 用 `use super::node_defs::...` / `use super::models::...`(确保那些函数已 `pub(super)`)。WorkflowValidateQuery struct 留 mod.rs `pub(super)`。
验证命令同上,提交 message:`refactor(workflow_ui): 抽出 validate 子模块`。
<!-- T7 -->
## Task 7: 抽 queue.rs(队列/历史/prompt/view)+ 收尾
**Files:** Create `src/routes/workflow_ui/queue.rs`;Modify `src/routes/workflow_ui/mod.rs`
要搬的函数:`queue_status`、`queue`、`queue_mutate`、`history`、`history_mutate`、`history_by_id`、`queue_prompt`、`repair_native_prompt_payload`、`queue_boosapi_prompt`、`interrupt`、`view`、`internal_logs`、`internal_logs_raw`。
- [ ] **Step 1-6: 按「通用抽取流程」执行**,`<name>` = `queue`。
注意:`repair_native_prompt_payload` 很长(2814-3474),依赖 node_defs/models 多个函数;`view` 用 serve_file/safe_view_path。补 `use super::...`。PromptPayload/HistoryQuery/ViewQuery/QueueMutation/UserDataQuery/UploadQuery struct 留 mod.rs `pub(super)`(被多模块用)。
验证命令同上,提交 message:`refactor(workflow_ui): 抽出 queue 子模块`。
- [ ] **Step 7: 最终验收**
Run:
```bash
cd /root/metapi
cargo build -j 2 2>&1 | tail -3
cargo test -p boosapi --lib routes::workflow_ui 2>&1 | grep "test result"
for f in mod auth node_defs models assets comfy_proxy validate queue; do echo -n "$f.rs: "; wc -l < src/routes/workflow_ui/$f.rs; done
```
Expected: Finished;测试数≥基线;每个子文件行数显著小于原 6181(mod.rs 应只剩 routes()+共享类型+小工具,目标 <1500 行;无单文件超 ~2000)。
- [ ] **Step 8: 冒烟(手动)**
部署后打开工作流 UI、跑一个 prompt,确认行为与拆分前一致(路由路径、handler 行为不变)。
<!-- END -->
docs/superpowers/specs/2026-06-16-billing-closed-loop-design.md
+149
View File
@@ -0,0 +1,149 @@
# 计费闭环系统设计
日期：2026-06-16
状态：设计已获批，待写实现计划
## 背景
BoosAPI 现有计费是零散拼接的：每个用户的 downstream API key 有 `max_cost`（美元上限）/ `used_cost`（已消耗），proxy 请求路径在 `used_cost >= max_cost` 时硬拦截返回 429；充值通过 Stripe 自动到账或 comfy_cloud 管理员确认到账，调用 `credit_user_balance` 增加 `max_cost`；新用户默认 $1 额度；usage_logs 按 key 记每笔消费。
缺口：ComfyUI 工作流执行不扣额度、无积分体系、无消费明细可视化、无充值档位配置、无低额度预警、无全量变动审计。
本设计把上述补齐为一个 **ledger-first（统一流水账）** 的计费闭环。
## 核心模型：双轨额度
- **USD 轨**：LLM 对话、生图、视频等所有走 `/v1/*` 的调用。沿用 `downstream_api_keys.max_cost/used_cost`。
- **工作流积分轨**：仅 ComfyUI 工作流执行。新建每用户独立的积分池，平台可管理。
两轨并行、互不换算。comfy_cloud 充值进积分轨；其他充值（Stripe）进 USD 轨。
## 数据模型
### 新表 `credit_ledger`（唯一真相源，所有变动记一行）
| 字段 | 类型 | 说明 |
|---|---|---|
| `id` | INTEGER PK AUTOINCREMENT | |
| `user_id` | INTEGER NOT NULL | 所属用户 |
| `track` | TEXT NOT NULL | `usd` / `points` |
| `entry_type` | TEXT NOT NULL | `recharge` / `admin_adjust` / `consume` / `refund` / `grant` |
| `amount` | REAL NOT NULL | 正=增 负=减（usd 用美元，points 用积分） |
| `balance_after` | REAL NOT NULL | 该轨本次变动后余额快照 |
| `ref_type` | TEXT | `usage_log` / `recharge_record` / `manual` / `stripe` 等 |
| `ref_id` | TEXT | 关联记录 id/public_id |
| `model` | TEXT | 消费类：模型名或工作流名（供聚合） |
| `operator` | TEXT | 操作者：管理员名 / `system` / `user` |
| `note` | TEXT | 备注 |
| `created_at` | TEXT DEFAULT (datetime('now')) | |
索引：`(user_id, created_at DESC)`、`(track, entry_type)`、`(user_id, track)`。
### 新表 `user_credits`（积分余额缓存）
| 字段 | 类型 | 说明 |
|---|---|---|
| `user_id` | INTEGER PK | |
| `points_balance` | REAL NOT NULL DEFAULT 0 | 当前积分余额（热路径读写） |
| `points_total_recharged` | REAL NOT NULL DEFAULT 0 | 累计充值积分（统计） |
| `updated_at` | TEXT | |
### 新表 `recharge_tiers`（充值档位，admin 可配）
| 字段 | 类型 | 说明 |
|---|---|---|
| `id` | INTEGER PK AUTOINCREMENT | |
| `track` | TEXT NOT NULL | `usd` / `points` |
| `amount_usd` | REAL NOT NULL | 支付金额（USD） |
| `grant_amount` | REAL NOT NULL | 到账量（USD 数或积分数） |
| `bonus` | REAL NOT NULL DEFAULT 0 | 赠送量 |
| `title` | TEXT | 档位标题 |
| `sort_order` | INTEGER DEFAULT 0 | 排序 |
| `enabled` | INTEGER DEFAULT 1 | 启用 |
### 余额派生策略：ledger + 缓存双写
- **USD 轨**：`max_cost/used_cost` 作快速余额缓存（拦截/展示零延迟读），每笔变动**同事务**写一条 `credit_ledger(track=usd)`。
- **积分轨**：`user_credits.points_balance` 作缓存，每笔变动**同事务**写 `credit_ledger(track=points)`。
- **关键不变量**：任何余额变动 = 缓存字段更新 + 一条 ledger，**同一 DB 事务**，事务失败整体回滚，绝不只改其一。
- ledger 是审计/明细/对账真相；缓存字段是热路径性能优化。
## 双轨记账接入
原则：所有动余额处，同事务"改缓存 + 写一条 ledger"。
### USD 轨
| 变动 | 现有代码 | 改造 |
|---|---|---|
| 充值到账 | `credit_user_balance`（payment.rs） | 同事务加写 ledger(usd, recharge) |
| 消费扣费 | `increment_key_usage`/`record_billing` | 同事务加写 ledger(usd, consume, model=模型名) |
| 管理员增减 | `adjust_user_balance` | 同事务加写 ledger(usd, admin_adjust, operator) |
| 额度拦截 | proxy `used_cost>=max_cost`→429 | 不变，补低额度预警信号 |
### 积分轨（基本新建）
| 变动 | 现状 | 新增 |
|---|---|---|
| 充值到账 | comfy_cloud 确认到账现加 USD | 改为加 `points_balance` + ledger(points, recharge) |
| 消费扣费 | 工作流不扣 | 工作流执行**成功后**按单价扣积分 + ledger(points, consume, model=工作流名)；失败不扣 |
| 管理员发放/增减 | 无 | 新增 `adjust_user_credits` + ledger(points, admin_adjust) |
| 积分拦截 | 无 | 工作流执行**前**检查 `points_balance >= 单价`，不足拒绝；低额度预警 |
- 积分消费扣费点：`workflow/executor.rs` 的 `run_workflow` 成功收尾处（有 `ctx.user_id`），与现有"工作流按用户 key 记 USD 消费"平行。
- **comfy_cloud 充值改向积分轨**：行为变更，历史 USD **不迁移**，仅对切换后新充值生效，用 config 开关控制（可回滚）。
## 积分消费规则：A+C 混合
- **A 固定/分级单价**（主）：工作流执行扣固定积分（config 默认值，可按工作流类型分级）。可预测、支持并发。
- **C 对账校准**（兜底）：后台 cron 拉 Comfy 总余额对账，偏差超阈值提示管理员调单价。
## 四块功能
### A 消费明细（用户侧，明细+聚合）
- 新建 `GET /api/user/billing/ledger`：查该用户 credit_ledger，可按 track/type/时间过滤。
- 新建 `GET /api/user/billing/summary`：按天/按模型聚合，双轨分开。
- 扩展 `UsageRecords.tsx`：双轨切换 + 聚合汇总卡 + 明细列表。
### B 充值档位（本期可配置，订阅后期）
- 新建 `recharge_tiers` 表 + admin CRUD `GET/POST/PUT/DELETE /api/admin/recharge-tiers`。
- 改造用户充值：档位从 DB 读（替代 env 写死的 `USER_RECHARGE_OPTIONS`）。
- 扩展 `UserRecharge.tsx`（档位从接口拉）+ 新建 admin `RechargeTiers` 配置页。
### C 超额 + 预警（两轨硬拦 + 预警）
- USD 拦截已有（不动）；积分拦截新建（工作流执行前）。
- 余额接口加 `lowBalance` 标志（余额 < 阈值，config 可配默认 20%）。
- Dashboard/充值页/视频助手：余额低显示预警条。
### D 审计对账（管理员侧，全量流水）
- 新建 `GET /api/admin/billing/ledger`：跨用户查 credit_ledger（按 user/track/type/时间过滤、分页）。
- 新建 admin `BillingAudit` 页：全量变动流水表（谁/何时/给谁/加减/原因），站点管理风格。
- 对账校准：cron 拉 Comfy 总余额，与积分消费 ledger 比对，偏差超阈值写 log + admin 告警标志。**不自动改数据**，仅提示，管理员手动调单价。
## 错误处理（不变量）
- 余额变动 = 缓存 + ledger 同事务；失败整体回滚。
- 消费扣费 best-effort 不阻断响应（沿用 record_billing 原则）。
- 积分轨：拦截是前置硬检查，扣费是后置；后置扣费失败已产出结果 → 记日志补偿。
- comfy 充值改向积分：config 开关控制，可回滚。
## 测试策略
- 单元：ledger 写入+缓存同步事务一致性；积分拦截（不足拒绝）；单价扣费；充值进积分；管理员调整双轨。
- 复用现有 payment/billing 测试框架（in-memory SQLite）。
## 实现顺序（分 6 期，每期可独立上线）
1. **地基**：credit_ledger + user_credits 表 + 迁移；USD 轨记账接进 ledger（充值/消费/调整三处双写）。
2. **积分轨**：工作流积分扣费 + 拦截 + comfy 充值改进积分 + 管理员积分调整。
3. **A 消费明细**：用户侧 ledger/summary 接口 + UsageRecords 扩展。
4. **B 充值档位**：recharge_tiers 表 + admin 配置页 + 用户充值页接 DB。
5. **C 预警**：余额接口加 lowBalance + 前端预警条。
6. **D 审计 + 对账**：admin BillingAudit 页 + cron 对账校准。
## 新增清单小结
- **表**：credit_ledger（核心）、user_credits（积分缓存）、recharge_tiers（档位）。
- **后端接口**：user billing ledger/summary、admin recharge-tiers CRUD、admin billing ledger、adjust_user_credits、积分拦截/扣费。
- **前端页面**：admin RechargeTiers、admin BillingAudit；扩展 UsageRecords / UserRecharge / Dashboard。
- **cron**：Comfy 余额对账校准任务。
docs/superpowers/specs/2026-06-17-comfy-cloud-adapter-design.md
+145
View File
@@ -0,0 +1,145 @@
# Comfy Cloud 工作流执行适配器 — 设计
日期:2026-06-17
分支:`feat/comfy-cloud-adapter`
状态:已通过 brainstorming,待落实现计划
## 背景
数字人/图片工作流走 `selfhost` 生成视频时报 `Submit workflow failed: [401] AuthenticationRequired`。
根因经多层验证已锁定:
- Pixelle 的 comfykit 0.1.12 `HttpExecutor` 说的是 **ComfyUI 原生协议**:
`POST {base_url}/prompt`、`GET {base_url}/history/{id}`、鉴权用 `Authorization: Bearer`。
- 配置里 `comfyui_url = https://cloud.comfy.org`,但 **Comfy Cloud 的 API 契约完全不同**
(官方文档 https://docs.comfy.org/development/cloud/overview):
- 鉴权:`X-API-Key` 头(非 Bearer)。
- 提交:`POST /api/prompt`(带 `/api/` 前缀)。
- 轮询:`GET /api/job/{prompt_id}/status` → 状态 pending/in_progress/completed/failed/cancelled。
- 详情/产出:`GET /api/jobs/{prompt_id}`(产出按 node_id 聚合 images/video/audio)。
- 下载:`GET /api/view?filename=&subfolder=&type=output`(302 跳带签名 URL)。
- 接受标准 ComfyUI API-format 工作流。
- 已用官方方式验证 Comfy Cloud key 有效:`GET /api/user` 返回 200 `{"status":"active"}`。
所以这不是 key 失效,而是 comfykit 与 Comfy Cloud 协议不兼容(路径前缀 + 鉴权头 + 轮询端点三处全不同)。
## 目标
在 **BoosAPI** 里实现一个 **ComfyUI 原生协议 ↔ Comfy Cloud API 翻译适配器**:对外暴露
ComfyUI 原生端点(`/prompt`、`/history/{id}`、`/view`),内部翻译成 Comfy Cloud 的
`/api/*` 契约 + `X-API-Key` 鉴权。Pixelle/comfykit **一行代码都不改**,只把 `comfyui_url`
指向 BoosAPI 的适配端点即可。
Comfy Cloud 的 base URL + API Key 通过**站点管理**录入(新增 `comfy_cloud` 平台类型),
适配器从站点配置读取,而非散落的环境变量/配置文件。
## 已确认的关键决策
1. 采用 **Approach A**:站点管理只作「配置载体 + 前端入口」(存 base_url + X-API-Key),
执行逻辑由独立的 Comfy Cloud 适配器承担;**不**把 Comfy Cloud 塞进 `/v1/*` token 路由
(它是工作流执行 API,不是聊天协议,塞进 token-router 跑不通)。
2. 适配器对外说 ComfyUI 原生协议,Pixelle/comfykit 零改动,只改 `comfyui_url` 配置。
3. 鉴权翻译:入口端点不强制校验(本机互信)/出口注入 `X-API-Key`。
4. 分支 `feat/comfy-cloud-adapter`,与 NIT 工作无关,不混入。
## 非目标
- 不改 Pixelle / comfykit 源码。
- 不做 WebSocket 实时进度(comfykit HTTP 模式只轮询 `/history/{id}`,够用)。
- 不把 Comfy Cloud 接入 LLM token 路由/failover。
- 不做 Comfy Cloud 的计费集成(已有 `fetch_comfy_cloud_balance` 另说)。
## 架构
```
Pixelle(comfykit 0.1.12, 不改)
comfyui_url = http://<boosapi-host>/comfy-cloud
说 ComfyUI 原生协议: POST /prompt · GET /history/{id} · GET /view · Bearer(忽略)
│
▼
BoosAPI 适配端点(新增 src/routes/comfy_cloud_adapter.rs)
· POST /comfy-cloud/prompt → 翻译 → POST cloud.comfy.org/api/prompt
· GET /comfy-cloud/history/{id} → 翻译 → GET /api/job/{id}/status (+ /api/jobs/{id})
拼回 ComfyUI history 格式
· GET /comfy-cloud/view → 翻译 → GET /api/view (跟随 302)
鉴权: 出口注入 X-API-Key(从站点配置读)
│
▼
Comfy Cloud (https://cloud.comfy.org/api/*)
```
## 站点管理集成(配置载体)
- 前端 `SITE_PLATFORM_OPTIONS`(`src/web/pages/Sites.tsx`)新增一项
`{ value: 'comfy_cloud', label: 'Comfy Cloud', description: '工作流执行 API' }`。
- 站点记录复用现有字段:`url` 存 `https://cloud.comfy.org`,API Key 存入现有的
站点凭证字段(沿用站点已有的 key/header 存储方式;实现时确认 sites 表里承载 key 的列)。
- 适配器通过一个 helper `resolve_comfy_cloud_site(state) -> (base_url, api_key)`:
查 `platform = 'comfy_cloud'` 且 enabled 的站点,取其 url + key。无配置 → 明确报错。
## 适配端点详细行为
### POST /comfy-cloud/prompt
- 入参:ComfyUI 原生 body `{ "prompt": {...}, "client_id": "..." }`。
- 出口:`POST {base_url}/api/prompt`,头 `X-API-Key: {key}` + `Content-Type: application/json`,
body 原样转发(Comfy Cloud 接受相同的 `{prompt: ...}` 包裹)。
- 回包:Comfy Cloud 返回 `{ "prompt_id": "..." }`,原样回给 comfykit(字段名一致,无需改)。
### GET /comfy-cloud/history/{prompt_id}
comfykit 轮询此端点,期待 ComfyUI history 格式:
`{ "{prompt_id}": { "status": {...}, "outputs": { "{node_id}": { "images": [...] } } } }`。
适配器:
1. `GET {base_url}/api/job/{prompt_id}/status` 拿 `{ "status": "completed|in_progress|..." }`。
2. 若未完成(pending/in_progress)→ 回 `{}`(comfykit 据此继续轮询)。
3. 若 completed → `GET {base_url}/api/jobs/{prompt_id}` 拿产出,翻译成 ComfyUI history 形状:
```json
{ "{prompt_id}": {
"status": { "completed": true, "status_str": "success" },
"outputs": { /* node_id → {images|video|audio: [{filename,subfolder,type}]} */ }
} }
```
4. 若 failed/cancelled → 回带 `status_str: "error"` 的 history,让 comfykit 终止轮询并报错。
### GET /comfy-cloud/view
- 透传 query(`filename`/`subfolder`/`type`)→ `GET {base_url}/api/view?...`,头注入 X-API-Key。
- Comfy Cloud 回 302 签名 URL → 适配器跟随重定向取字节流回传(reqwest 默认跟随,
或手动取 Location 再 GET),Content-Type 透传。
## 数据流(comfykit 视角,全程无感)
1. comfykit `POST {comfyui_url}/prompt` → 适配器 → Comfy Cloud → 返回 prompt_id。
2. comfykit 轮询 `GET {comfyui_url}/history/{id}` → 适配器翻译 job 状态 → 未完成回 `{}`,
完成回 ComfyUI history。
3. comfykit 从 outputs 取 filename → `GET {comfyui_url}/view?filename=...` → 适配器取回字节。
## 错误处理
- 站点未配置 `comfy_cloud` → 适配端点返回 503 + 中文提示「未配置 Comfy Cloud 站点」。
- Comfy Cloud 返回非 2xx → 适配器透传状态码 + 上游错误体(便于排查,不吞错)。
- job failed/cancelled → 在 history 里标 error,comfykit 会抛 `Submit workflow failed` 类错误
(但这次是真实的执行失败,不是鉴权问题)。
## 路由挂载
`src/routes/mod.rs` 的 `build_router` 加 `.merge(comfy_cloud_adapter::routes())`。
端点前缀 `/comfy-cloud/*`,不需要 admin/user 鉴权(本机内 Pixelle → BoosAPI 互信;
如需收紧可后续加内部 token,本期不做)。
## 测试策略(TDD)
- 单测翻译函数:Comfy Cloud `job status + jobs detail` JSON → ComfyUI history JSON 的纯函数
(`comfy_cloud_job_to_history`),覆盖 completed / in_progress / failed 三种。
- 单测 `resolve_comfy_cloud_site`:有配置返回 (url,key);无配置报错。
- 用 wiremock 起一个假 Comfy Cloud,集成测 `POST /comfy-cloud/prompt` 透传 + X-API-Key 注入、
`GET /comfy-cloud/history/{id}` 轮询翻译(沿用项目现有 wiremock 测试范式)。
## 验证
- `cargo build -j 2`、`cargo test -p boosapi --lib comfy_cloud`。
- 真实联调:把 Pixelle `comfyui_url` 指向 `http://<boosapi>/comfy-cloud`,跑一次 selfhost 视频,
确认不再 401 且能取回产出。
## 提交约定
分支 `feat/comfy-cloud-adapter`,提交按逻辑拆分(站点平台类型 / 适配器 service + 端点 /
路由挂载 / 前端平台选项),沿用项目中文 commit 风格。
docs/superpowers/specs/2026-06-18-digital-human-comfy-video-entry-design.md
+93
View File
@@ -0,0 +1,93 @@
# 数字人接入 Comfy Cloud 视频工作流(完整视频入口)设计
日期:2026-06-18
分支:`feat/comfy-cloud-adapter`
状态:已通过调查,待用户复审
## 背景
LTX2.3 说话头像工作流(`comfy/video_digital_ltx2.json`)已就绪并通过 Comfy Cloud 校验
(节点+模型全兼容,probe `node_errors:{}`)。但 BoosAPI 数字人 UI 没有「视频/动画工作流」
入口,无法触发「肖像图 + 旁白音频 → 说话视频」这一步。本设计补齐贯穿三层的入口。
## 现状(调查结论)
- **BoosAPI 数字人前端 `src/web/pages/DigitalHuman.tsx`**:仅 3 个选择器——ttsWorkflow、
imageWorkflow(从 mediaWorkflows 选,默认含 "image" 的)、frameTemplate(HTML 模板)。
**无视频/动画工作流选择器**。流程是「生成图片 + TTS + HTML 模板合成」,不做说话头像动画。
- **BoosAPI 后端 `src/routes/digital_human.rs`** 的 `pixelle_request_body`(~line 2053):转发
text/mode/title/backend_provider/workflow_source/n_scenes/video_fps/frame_template/
template_params/prompt_prefix/bgm_*/media_workflow/tts_workflow/ref_audio。
**不转发 `api_video_workflow`**;`workflow_source` 写死 `runninghub`/`selfhost`(无 comfy)。
- **Pixelle `pixelle_video/pipelines/asset_based.py`**(~line 693):动画步读
`context.request.get("api_video_workflow")`;`audio_path` 仅当 `_get_api_workflow_info`
(查 `api_media`,只 `api/` 通道)匹配到 `audio_driven_i2v` 能力时才注入 → **comfy 工作流
拿不到 audio_path**。
- **Pixelle 工作流执行按前缀路由**:`runninghub` 走 RunningHub,其余(含 `comfy/`)走
`comfyui_url`(= BoosAPI `/comfy-cloud` 适配器)。`comfy/video_digital_ltx2.json` 已在
`/workflows/media` 列出(已加 `video_` 前缀)。
- 已完成的前置:comfy-cloud 适配器(已验证)、`comfy/video_digital_ltx2.json`(标记
image_path/audio_path/prompt,probe 通过)、media.py 转发 image_path(已打补丁)。
## 已确认决策
1. 加完整视频入口:前端选择器 + 后端转发 + Pixelle 音频注入,三层都改。
2. 视频工作流选择器列 `video_*` media 工作流(含 `comfy/video_digital_ltx2.json`)。
3. 单人肖像说话头像;不做多人。
## 三层改动设计
### 层 1:前端 `src/web/pages/DigitalHuman.tsx`
- 新增 state `apiVideoWorkflow`(默认空=不启用动画,保持现有「图片+HTML」行为向后兼容)。
- 新增「视频工作流(可选)」`<select>`:选项 = `mediaWorkflows.filter(name 含 "video")`,
含空选项「不生成视频(仅图片合成)」。
- 提交 payload 增加 `apiVideoWorkflow` 字段;draft 持久化同步。
### 层 2:BoosAPI 后端 `src/routes/digital_human.rs`
- `pixelle_request_body` 增加:
```rust
if let Some(value) = optional_string(body, &["apiVideoWorkflow", "api_video_workflow"]) {
request_body["api_video_workflow"] = json!(value);
}
```
- 若所选视频工作流以 `comfy/` 开头,确保 `workflow_source` 不会阻断(comfy 工作流靠前缀
路由,workflow_source 主要影响 media/tts 默认通道;api_video_workflow 独立按前缀执行,
无需改 workflow_source。实现时验证不冲突)。
- 可选转发 `api_video_params`(若前端给了音频驱动等参数)。本期最小化:只转发 api_video_workflow。
### 层 3:Pixelle `pixelle_video/pipelines/asset_based.py`
- 动画步注入 `audio_path` 的条件放宽:除 `api_media` 能力匹配外,**当 `api_video_workflow`
以 `comfy/` 开头时,也注入 `audio_path = frame.audio_path`**(comfy 工作流的 `$~audio_path!`
标记需要它)。最小改动:在 `audio_driven_i2v` 判断旁边加 comfy 前缀分支。
- 镜像内置文件,改后重启容器,备份到 `/opt/Pixelle-Video/patches/`。
## 数据流(目标)
```
DigitalHuman.tsx: 选 comfy/video_digital_ltx2.json (apiVideoWorkflow)
→ BoosAPI digital_human.rs: request_body.api_video_workflow
→ Pixelle /api/video/generate/async: context.request.api_video_workflow
→ asset_based.py 动画步: 注入 image_path(media.py已补)+ audio_path(本期补)+ prompt
→ media() comfy 前缀 → comfyui_url=/comfy-cloud 适配器 → Comfy Cloud LTX2.3
→ 说话视频 → 帧合成/HTML 模板 → 成片
```
## 验证
- 前端 typecheck:`npm run typecheck:web`。
- 后端构建:`cargo build -j 2`。
- Pixelle 改动:语法校验 + 重启 healthy。
- 端到端:数字人任务选 `comfy/video_digital_ltx2.json`,确认 Comfy Cloud 出现 job、
注入了 image_path+audio_path、出说话视频。
## 非目标
- 不改 comfy-cloud 适配器(已完成)。
- 不做多人对话数字人。
- 不重构数字人现有「图片+HTML 合成」路径(视频入口为可选叠加,默认不启用,向后兼容)。
- 不动 RunningHub 数字人路径。
## 提交约定
分支 `feat/comfy-cloud-adapter`。前端、BoosAPI 后端分别提交(项目内,受版本控制);
Pixelle 改动在容器内 + 备份 patches/(非本仓库)。中文 commit。
docs/superpowers/specs/2026-06-18-digital-human-llm-model-select-design.md
+71
View File
@@ -0,0 +1,71 @@
# 数字人脚本 LLM 模型可选 设计
日期:2026-06-18
分支:`feat/comfy-cloud-adapter`
状态:已通过 brainstorming,待用户复审
## 背景
数字人脚本生成的 LLM 模型现在写死在 Pixelle config(`llm.model = gpt-5.5`),用户无法在
数字人页面选用别的模型。本功能加一个「脚本模型(可选)」下拉,让用户自选生成脚本的 LLM。
生图模型已可通过现有「图片工作流」下拉选择,不在本范围。
## 已确认决策
1. 只做脚本 LLM 模型可选;生图模型已由「图片工作流」下拉覆盖,不动。
2. 下拉只列文本/对话模型(过滤掉生图/视频模型,避免选错导致生成失败)。
3. 默认空 = 用 Pixelle config 的默认模型(`deepseek-v4-flash`),向后兼容。实现时把 Pixelle
`config.yaml` 的 `llm.model` 设为 `deepseek-v4-flash`。
4. 三层改动(前端选择器 + 后端转发 + Pixelle 传 model)。
## 集成点(调查结论)
- Pixelle `llm_service.py`:`llm(prompt=, model=...)` **已支持按调用传 model 覆盖**
(优先级:参数 > config)。
- Pixelle `asset_based.py` 脚本生成调用 `self.core.llm(prompt=, response_type=VideoScript, ...)`
**当前未传 model** → 需补 `model=context.request.get("llm_model")`。
- BoosAPI `digital_human.rs` `pixelle_request_body` 转发字段(媒体/tts 工作流等),
**未转发 llm_model** → 需补。
- 前端模型列表:`api.getModelsMarketplace()`(`/api/models/marketplace`)已有,可作下拉数据源。
- `/v1/models` 需鉴权(401 直取不行),故用 marketplace 接口。
## 三层改动设计
### 层1 前端 `src/web/pages/DigitalHuman.tsx`
- 加 state `llmModel`(默认空)+ draft 持久化。
- 加载时调 `api.getModelsMarketplace()` 取模型,过滤掉生图/视频模型(名称含
image/video/dall/flux/sd/wan/seedance/kling/banana 等,或按 marketplace 项的类型字段),
得文本模型列表 state `llmModels`。
- 加「脚本模型(可选)」`<select>`:空选项「默认(deepseek-v4-flash)」+ 文本模型选项。
- 提交 payload 加 `llm_model: llmModel || undefined`。
### 层2 后端 `src/routes/digital_human.rs`
- `pixelle_request_body` 加(照搬 tts_workflow 转发模式):
```rust
if let Some(value) = optional_string(body, &["llmModel", "llm_model"]) {
request_body["llm_model"] = json!(value);
}
```
### 层3 Pixelle `pixelle_video/pipelines/asset_based.py`
- 脚本生成调用前取 `llm_model = context.request.get("llm_model")`,非空则传入:
`self.core.llm(prompt=prompt, response_type=VideoScript, temperature=0.8, max_tokens=4000, model=llm_model)`。
(llm() 已接受 model 参数;None 时走 config 默认。)
- 容器内改 + 备份到 `/opt/Pixelle-Video/patches/`。
## 验证
- 前端 `npm run typecheck:web` 干净。
- 后端 `cargo build -j 2` 通过。
- Pixelle 语法校验 + 重启 healthy。
- 端到端:数字人任务选非默认脚本模型,Pixelle 日志出现 `LLM call: model=<所选模型>`。
## 非目标
- 不改生图模型选择(已由图片工作流下拉覆盖)。
- 不做参考图上传(功能 B,留后续)。
- 不动 comfy-cloud 适配器、LTX2.3 工作流。
## 提交约定
分支 `feat/comfy-cloud-adapter`。前端、后端分别提交;Pixelle 容器内改 + 备份(非本仓库)。中文 commit。
docs/superpowers/specs/2026-06-18-ltx2-digital-human-workflow-design.md
+93
View File
@@ -0,0 +1,93 @@
# LTX2.3 数字人工作流(Comfy Cloud)设计
日期:2026-06-18
分支:`feat/comfy-cloud-adapter`
状态:已通过 brainstorming,待落实现计划
## 背景
Pixelle 数字人(说话头像)能力原先只有 RunningHub 形态(`runninghub/digital_*.json` 是
`{"source":"runninghub","workflow_id":"..."}` 指针,非 ComfyUI 节点图,无法在 Comfy Cloud 跑)。
为让数字人走 Comfy Cloud,采用官方 ComfyUI 模板 `video_ltx2_3_id_lora`(LTX2.3 身份保持
LoRA + 音频驱动),把它做成 Pixelle 的 `comfy/` 工作流,经已建好的 comfy-cloud 适配器执行。
可行性已验证(查 Comfy Cloud `/object_info` 3548 节点 + 模型池):
- 模型齐全:`ltx-2.3-22b-dev-fp8`、`ltx-2.3-id-lora-talkvid-3k`、`gemma_3_12B_it_fp4_mixed`、
distilled LoRA 均托管;另有 `ltx-2.3-22b-ic-lora-lipdub-0.9` 口型 LoRA。
- 节点齐全:LTX2.3 音视频节点(LTXVReferenceAudio/LTXVConcatAVLatent/LTXVAudioVAEDecode 等)
全在 Comfy Cloud 节点集中。
- 模板 I/O = LoadImage(肖像)+ LoadAudio(旁白)+ 文本 → SaveVideo(带音频说话视频),
正好匹配数字人。
## 已确认决策
1. 用官方模板 `video_ltx2_3_id_lora`(LTX2.3),不自拼 InfiniteTalk(官方模板天然 Comfy-Cloud
兼容、模型已托管、风险低)。
2. 接入方式:comfy 通道 + 节点图注入(放 `comfy/digital_ltx2.json`,经适配器),不走 RunningHub、
不另做独立入口。
3. comfykit 注入机制:节点 `_meta.title` 标记(`$~image!` / `$~audio!` / `$prompt!`)。
4. 分支 `feat/comfy-cloud-adapter`(与 comfy-cloud 适配器同分支,属同一能力线)。
## 前置依赖(硬依赖)
**需要用户从 Comfy Cloud 导出 API 格式 JSON**:模板当前是 UI 格式(含 subgraph 子图),
`/api/prompt` 要求 API 格式(`{node_id:{class_type,inputs,_meta}}`)。子图必须展开。
用户操作:Comfy Cloud 网页打开模板/share → Workflow → Export (API Format) → 放服务器
(如 `/tmp/ltx2_api.json`)。服务端无法代取(需登录态)。
## Pixelle media.py 改动(writing-plans 阶段发现的必需项)
现状:`pixelle_video/services/media.py` 的 `__call__` 只把 `image_path` 转发给 `api/` 通道
(`api_media`),**comfy/ 通道的 workflow_params 不含 image_path**。`audio_path` 经 `**params`
能进 workflow_params,但肖像图进不去。所以 comfy/ 工作流收不到肖像图。
改动:在 `media.py` 的非 api/ 分支(构建 `workflow_params` 处),把 `image_path` 也加入
`workflow_params`(命名 `image_path`),使其能被 `$~image_path!` 标记注入。一行级小改,
但属 Pixelle 源码(非 BoosAPI 仓库),改在容器内 `/app/pixelle_video/services/media.py`,
并同步到宿主持久化(确认 media.py 是否在挂载卷;若在镜像内则需固化方案)。
## 架构
```
Pixelle 数字人流程
生成肖像图(image_path)+ TTS 旁白(audio_path)+ 脚本文本
│ comfykit 按 _meta.title 标记注入到 LoadImage/LoadAudio/文本节点
▼
comfy/digital_ltx2.json (API 格式 + 标记)
│ comfyui_url = http://<boosapi>/comfy-cloud
▼
Comfy Cloud /api/prompt → LTX2.3(id-lora-talkvid + 可选 lipdub)→ 带音频说话视频
▼
SaveVideo 产出 → 适配器 /view 取回 → Pixelle HTML 模板合成
```
## 工作流改造(实现步骤)
基于用户导出的 API-format JSON:
1. `LoadImage` 节点 → `_meta.title = "$~image_path!"`(必填、媒体上传;键名对齐 media.py 转发的 image_path)
2. `LoadAudio` 节点 → `_meta.title = "$~audio_path!"`(键名对齐 api_video_params 注入的 audio_path)
3. 文本提示节点(PrimitiveStringMultiline / CLIPTextEncode)→ `_meta.title = "$prompt!"`(对齐 media.py 的 prompt)
4. `SaveVideo` 已知输出节点,自动识别,不标记
5. 删除 `RecordAudio` 节点(UI 录音交互,服务端不需要)
6. 成品写 `data/workflows/comfy/digital_ltx2.json`(宿主持久化,经 `./data` 挂载)
7. 键名以 media.py 实际放入 workflow_params 的为准(image_path/audio_path/prompt),已在 writing-plans 阶段确认。
## 验证
- 校验探测:`POST /comfy-cloud/prompt`(body 为改造后 `{prompt:节点图}`)→ 期望
`node_errors:{}` + 返回 prompt_id(不跑完整数字人流程,先验证节点+模型全兼容)。
- 真实验证:Pixelle 数字人任务选 `comfy/digital_ltx2.json`,出片确认。
- 错误处理沿用适配器:节点不支持→400 透传;模型缺失→校验错误透传;执行失败→job failed。
## 非目标
- 不改 comfy-cloud 适配器代码(已完成且验证)。
- 不做多人对话(multi-speaker)数字人,先单人肖像。
- 不在 Comfy Cloud 上自训/上传新模型,只用已托管模型。
- 不做 RunningHub 数字人的迁移/替换(保留并存)。
## 提交约定
分支 `feat/comfy-cloud-adapter`,工作流文件 + 任何 Pixelle 侧配置分开提交,中文 commit。
注:工作流文件落在 Pixelle 宿主目录(`/opt/Pixelle-Video/data/workflows/comfy/`),不在
BoosAPI 仓库内;若需纳入版本管理另议。
docs/superpowers/specs/2026-06-18-pixelle-connection-management-design.md
+90
View File
@@ -0,0 +1,90 @@
# Pixelle 连接凭证纳入 BoosAPI 管理 设计
日期:2026-06-18
分支:`feat/comfy-cloud-adapter`
状态:已通过 brainstorming,待用户复审
## 背景
Pixelle 的连接凭证(RunningHub API key、Comfy Cloud url/key)现在只能手动编辑
`/opt/Pixelle-Video/config.yaml` 再重启容器,很麻烦。本功能把这 3 个凭证纳入 BoosAPI
管理控制台,在 UI 里改、一键写入 Pixelle config 并重启生效。
## 已确认决策
1. 范围:只管 Pixelle 的 3 个连接凭证 —— `runninghub_api_key`、`comfyui_url`、`comfyui_api_key`。
不做整份 config.yaml 编辑,不做通用外部连接管理。
2. 同步机制:写文件 + 重启容器(BoosAPI 直接改 bind-mount 的 config.yaml,再 restart pixelle 容器)。
不给 Pixelle 加 HTTP 配置端点(避免改 Pixelle 源码)。
3. 真相源:BoosAPI settings 表;config.yaml 是被同步的目标。
4. 放置:连接管理页(`/accounts`,`src/web/pages/Accounts.tsx`)作为一个卡片/分区。
## 集成点(调查结论)
- Pixelle 无配置更新 HTTP 端点;`config.yaml` 是 bind-mount(`/opt/Pixelle-Video/config.yaml`),
BoosAPI 跑在宿主,有读写权限。
- 凭证在 config.yaml 的 `comfyui:` 段:`runninghub_api_key` / `comfyui_url` / `comfyui_api_key`。
- 改后 Pixelle 需重启容器生效(`cd /opt/Pixelle-Video && docker compose restart api`)。
- BoosAPI 有 settings 表(key-value)+ builtin_key 掩码范式可复用。
## 架构
```
连接管理页「Pixelle 连接」卡片(3 输入框 + 保存)
→ PUT /api/admin/pixelle/connection
1. 写 settings 表(pixelle.runninghub_api_key 等)
2. 备份 config.yaml → config.yaml.bak-<ts>
3. YAML 改 comfyui.{runninghub_api_key,comfyui_url,comfyui_api_key} 三键(其余保留)
4. docker compose restart api(cwd=/opt/Pixelle-Video)
→ GET /api/admin/pixelle/connection 返回当前值(密钥掩码)
```
## 三层改动设计
### 层1 后端 service `src/services/pixelle_connection.rs`(新建)
- `struct PixelleConnection { runninghub_api_key, comfyui_url, comfyui_api_key }`(均 Option<String>)。
- `read_connection(db) -> PixelleConnection`:从 settings 表读 `pixelle.*` 三键。
- `save_connection(db, conn)`:三键写 settings 表(UPSERT)。
- `sync_to_pixelle(config_path) -> AppResult<()>`:读 yaml → 改 comfyui 三键 → 备份 → 写回。
用 `serde_yaml`(确认 Cargo.toml 有;无则加)。只改这三键,其余键原样保留(读成
`serde_yaml::Value` 再定点改,不整体重序列化丢注释——注意:serde_yaml 会丢注释,
接受此代价,或保留备份)。
- `restart_pixelle(compose_dir) -> AppResult<()>`:`docker compose restart api`,cwd=compose_dir。
- 配置项:Pixelle config 路径 + compose 目录,默认 `/opt/Pixelle-Video/config.yaml`、
`/opt/Pixelle-Video`,从 BoosAPI config(新增 `[pixelle_video] config_path` / 复用现有)读。
### 层2 后端路由 `src/routes/admin/pixelle_connection.rs`(新建)+ 挂载
- `GET /api/admin/pixelle/connection`:返回三值,api_key 掩码(`••••<last4>`)。
- `PUT /api/admin/pixelle/connection`:收三字段 → save_connection → sync_to_pixelle → restart。
掩码值(`••••`)表示「不改」,跳过该字段。
- 挂到 admin router(走现有 require_admin 中间件)。
### 层3 前端 `src/web/pages/Accounts.tsx` + `api.ts`
- `api.ts` adminApi 加 `getPixelleConnection()` / `savePixelleConnection(data)`。
- Accounts 页加「Pixelle 连接」卡片:3 输入框(runninghub key、comfy url、comfy key)+ 保存。
加载时拉当前值(掩码),保存提示「已保存并重启 Pixelle，约数秒生效」。
## 错误处理
- config.yaml 不存在/无写权限 → 503 + 明确提示,**不重启**。
- docker restart 失败 → 返回错误,提示「配置已写入,但 Pixelle 重启失败,请手动重启」。
- 写文件前必备份;写失败保留原文件。
## 验证
- 后端:rstest 用临时 yaml 测 sync_to_pixelle(读→改3键→保留其余→备份生成);
`cargo build -j 2`。
- 前端:`npm run typecheck:web`。
- docker restart 部分手动验证(端到端:UI 改 runninghub key → 确认 config.yaml 变 + 容器重启)。
## 非目标
- 不做整份 config.yaml 编辑。
- 不做通用「外部服务连接」管理(只 Pixelle)。
- 不给 Pixelle 加源码/端点。
- 不动 comfy-cloud 适配器、数字人工作流。
## 提交约定
分支 `feat/comfy-cloud-adapter`。service / 路由 / 前端 分开提交,中文 commit。
serde_yaml 若需新增依赖,单独说明。
docs/superpowers/specs/2026-06-18-workflow-ui-mod-split2-design.md
+58
View File
@@ -0,0 +1,58 @@
# workflow_ui/mod.rs 续拆(6 子模块)设计
日期:2026-06-18
分支:`feat/comfy-cloud-adapter`
状态:已通过 brainstorming,待用户复审
## 背景
上一轮已把 `workflow_ui.rs`(6181 行)拆成 8 模块,但 `mod.rs` 仍 4095 行——一批
未在上轮清单内的函数(native proxy / repair 链 / bootstrap 注入 / run 转换 / ws / 模型注入)
留在了 mod.rs。本轮继续把这 6 组抽出,让 mod.rs 瘦到 ~1000-1200 行(只剩 routes()
+ 共享 struct + 小工具)。
延续上轮纪律:**纯机械移动,函数体一字不改**,只调可见性 + use,编译器 + 5 测试验证。
## 已确认决策
1. 续拆 workflow_ui/mod.rs 残留。
2. 拆成 6 子模块(见下表)。
3. 纯机械移动,零逻辑改动。
4. 安全:每抽一组即 cargo build -j 2 + 5 测试保持;末尾各文件行数核对。
## 子模块划分
| 子模块 | 函数组 |
|--------|--------|
| `model_inject.rs` | comfy_combo_input, inject_model_choices, is_boosapi_extension_node_type, workflow_node_defs_with_models, inject_boosapi_object_info, builtin_model_folders, inject_boosapi_model_folders, workflow_model_folder_payload, native_model_folder_payload_or_fallback, model_payload_items_from_names, normalize_model_item_name, workflow_model_display_aliases, model_payload_item_with_name, merge_model_payload_items, normalize_model_folder_payload |
| `repair.rs` | inject_native_prompt_cloud_api_key, repair_resize_image_mask_nodes(+_without_workflow), repair_text_generate_ltx2_prompt_nodes, repair_dynamic_combo_nodes(+ dynamic_combo_* 全部 helper), repair_wan2_api_nodes(+ wan2_* / is_wan2_* helper), collect_workflow_nodes, prompt_subgraph_node_id, id_to_prompt_key |
| `native_proxy.rs` | native_workflow_enabled/base/http_path/request/json/json_cached/response/view_response/video_response/file_response/raw_response/api_proxy, archive_native_workflow_asset, repair_native_prompt_body_value, workflow_cache_kind_from_key, workflow_cache_status, upload_image(+_to_local_backend/_to_native_backend), upload_mask, timestamp_ms |
| `run_convert.rs` | workflow_run_to_history/_task/_queue_task/_prompt_tuple, run_status_messages, run_outputs_for_comfy, node_output_for_comfy, comfy_media_items, normalize_comfy_media_item, workflow_text_output, workflow_graph_to_comfy_workflow, workflow_timestamp_ms |
| `ws.rs` | workflow_session_sender, publish_workflow_ws_event, workflow_node_label, workflow_progress_callback_with_run_sender, publish_run_events, workflow_ws, native_workflow_ws_bridge |
| `bootstrap.rs` | inject_bootstrap, workflow_secret_cleanup_bootstrap, inject_external_bootstrap, inject_enhanced_bootstrap |
> 留 mod.rs:routes()、共享 struct(WorkflowCaller/CachedJson/各 Query/Payload)、跨多模块小工具
> (safe_view_path/user_home/guess_mime_from_path/parse_boolish/auth_caller_optional/
> workflow_context/parse_workflow_cookie/build_query_string/simple_urlencode/各 workflow_widget_*
> validation helper 等)、experiment_models/view_metadata/custom_nodes_i18n/internal_* 等零散 handler。
> 实现时按实际依赖判定:被多组共用的留 mod.rs `pub(super)`。
## 安全策略
同上轮:每抽一组 → `cargo build -j 2`(编译器是主安全网,纯移动)→ `cargo test -p boosapi
--lib routes::workflow_ui`(5 测试基线不减)→ 提交。跨模块依赖的私有符号按编译报错逐个
改 `pub(super)`。子模块内部 helper 也 `pub(super)` 或保持模块私有(看是否跨文件用)。
## 测试
编译器逐组验证;5 个现有测试全程保持;末尾核对 8+6 个子文件行数,mod.rs 应 <1500。
## 非目标
- 不改逻辑、不改路由、不动 handler 行为。
- 不拆其他巨文件(oauth/payment/digital_human 各自后续循环)。
- 不顺手优化函数实现。
## 提交约定
分支 `feat/comfy-cloud-adapter`。每抽 1 组 + 编译通过即提交。中文 commit。
docs/superpowers/specs/2026-06-18-workflow-ui-split-design.md
+69
View File
@@ -0,0 +1,69 @@
# workflow_ui.rs 拆分(8 子模块)设计
日期:2026-06-18
分支:`feat/comfy-cloud-adapter`
状态:已通过 brainstorming,待用户复审
## 背景
`src/routes/workflow_ui.rs` 单文件 6181 行,是项目最大文件,难维护/难测/edit 易错。
按职责拆成 `src/routes/workflow_ui/` 模块目录(8 子模块)。纯机械移动、零逻辑改动,
靠 Rust 编译器 + 现有 5 个测试验证。
## 已确认决策
1. 第一个优化目标:拆 workflow_ui.rs(项目最大文件)。
2. 拆成 8 子模块(见下表)。
3. 纯机械移动:函数体一字不改,只调可见性 + use 路径。零逻辑改动。
4. 安全策略:每抽一个子模块即 cargo build -j 2 验证;5 个测试全程保持通过;末尾冒烟。
## 子模块划分
| 子模块 | 职责 | 现有行号(约) |
|--------|------|--------------|
| `mod.rs` | routes() 装配 + 共享类型(WorkflowCaller、Query/Payload structs)+ 子模块声明 | 56-124 |
| `assets.rs` | UI 静态资源服务、嵌入目录解析、index/static/serve_file/官方模板资源 | 211-305, 1533-1814 |
| `auth.rs` | caller 解析(caller_from_headers/auth_caller/caller_user_id/caller_is_admin) | 313-363, 1875 |
| `node_defs.rs` | 节点定义 + 工作流模板(core_node_definitions、*_workflow_graph、node_type_def_to_comfy) | 429-932 |
| `models.rs` | 模型分类 + folder 模型(is_*_workflow_model、workflow_folder_*、native_folder_models) | 939-1530 |
| `comfy_proxy.rs` | ComfyUI API 代理 handler(settings/userdata/object_info/system_stats/extensions 等) | 1883-2200 |
| `validate.rs` | 工作流校验(validate_workflow* 三个) | 2206-2586 |
| `queue.rs` | 队列/历史/prompt(queue/history/queue_prompt/repair_native_prompt_payload/queue_boosapi_prompt/view) | 2586-3679 |
> 注:行号是当前快照,实现时以函数名定位为准(文件会随抽取缩短)。各子模块的辅助小函数
> 随其主要消费者走;跨多模块共用的(如 guess_mime_from_path、parse_boolish、safe_view_path)
> 放 mod.rs 或新建 util.rs(实现时按实际依赖定,优先放 mod.rs 顶部 pub(super))。
## 安全策略(核心)
1. **纯移动**:剪切函数到子模块,函数体一字不改。仅:
- 可见性:跨模块调用的改 `pub(super)` / `pub(crate)`;
- `use`:子模块顶部补齐它用到的依赖路径(crate::、super::、外部 crate)。
2. **逐模块验证**:每抽一个子模块就 `cargo build -j 2`。Rust 编译器对未解析引用/类型不符
直接报错——这是纯移动重构的强安全网。
3. **测试保持**:现有 5 个测试(在文件尾 `#[cfg(test)] mod tests`)迁到相关子模块(多与
models/node_defs 相关),全程保持通过:`cargo test -p boosapi --lib routes::workflow_ui`。
4. **末尾冒烟**:全部完成后,工作流 UI 打开 + 跑一个 prompt,确认行为不变。
## 数据流
不变。`routes/mod.rs` 仍 `.merge(workflow_ui::routes())`,对外接口零变化。仅文件内部
组织从 1 文件变 8 文件,所有路由路径、handler 行为、类型签名完全一致。
## 测试
- 编译器:每步 cargo build -j 2(主验证手段)。
- 单测:迁移后 5 个测试保持通过。
- 冒烟:手动开工作流 UI + 跑 prompt。
- 不新增功能测试(本任务是重构,非加功能;但若迁移中发现某函数明显缺测且易加,可顺手补)。
## 非目标
- 不改任何逻辑、不改路由路径、不改 handler 行为。
- 不拆其他巨文件(oauth.rs/digital_human.rs/user/mod.rs 各自独立后续循环)。
- 不顺手重构/优化函数实现(纯搬运)。
## 提交约定
分支 `feat/comfy-cloud-adapter`。**按子模块分多次提交**(每抽 1-2 个子模块 + 编译通过即提交),
便于回溯;不一锅烩。中文 commit。
migrations/20260516000001_initial.sql
+868
View File
@@ -0,0 +1,868 @@
-- BoosAPI initial schema
-- Generated from the existing SQLite database (hub.db)
-- This migration creates all tables, indexes, and constraints.
-- ============================================================
-- SITES
-- ============================================================
CREATE TABLE IF NOT EXISTS sites (
id INTEGER PRIMARY KEY AUTOINCREMENT NOT NULL,
name TEXT NOT NULL,
url TEXT NOT NULL,
platform TEXT NOT NULL,
status TEXT NOT NULL DEFAULT 'active',
api_key TEXT,
proxy_url TEXT,
use_system_proxy INTEGER DEFAULT false,
custom_headers TEXT,
external_checkin_url TEXT,
global_weight REAL DEFAULT 1,
post_refresh_probe_enabled INTEGER DEFAULT false,
post_refresh_probe_model TEXT DEFAULT '',
post_refresh_probe_scope TEXT DEFAULT 'single',
post_refresh_probe_latency_threshold_ms INTEGER DEFAULT 0,
is_pinned INTEGER DEFAULT false,
sort_order INTEGER DEFAULT 0,
created_at TEXT DEFAULT (datetime('now')),
updated_at TEXT DEFAULT (datetime('now'))
);
CREATE UNIQUE INDEX IF NOT EXISTS sites_platform_url_unique
ON sites (platform, url);
CREATE INDEX IF NOT EXISTS sites_status_idx
ON sites (status);
-- ============================================================
-- USERS
-- ============================================================
CREATE TABLE IF NOT EXISTS users (
id INTEGER PRIMARY KEY AUTOINCREMENT NOT NULL,
username TEXT NOT NULL,
email TEXT NOT NULL,
password_hash TEXT NOT NULL,
role TEXT NOT NULL DEFAULT 'user',
status TEXT NOT NULL DEFAULT 'active',
created_at TEXT DEFAULT (datetime('now')),
updated_at TEXT DEFAULT (datetime('now'))
);
CREATE UNIQUE INDEX IF NOT EXISTS users_email_unique
ON users (email);
CREATE INDEX IF NOT EXISTS users_status_idx
ON users (status);
-- ============================================================
-- TOKEN ROUTES
-- ============================================================
CREATE TABLE IF NOT EXISTS token_routes (
id INTEGER PRIMARY KEY AUTOINCREMENT NOT NULL,
model_pattern TEXT NOT NULL,
model_mapping TEXT,
display_name TEXT,
display_icon TEXT,
decision_snapshot TEXT,
decision_refreshed_at TEXT,
routing_strategy TEXT DEFAULT 'weighted',
route_mode TEXT DEFAULT 'pattern',
enabled INTEGER DEFAULT true,
created_at TEXT DEFAULT (datetime('now')),
updated_at TEXT DEFAULT (datetime('now'))
);
CREATE INDEX IF NOT EXISTS token_routes_model_pattern_idx
ON token_routes (model_pattern);
CREATE INDEX IF NOT EXISTS token_routes_enabled_idx
ON token_routes (enabled);
-- ============================================================
-- ACCOUNTS
-- ============================================================
CREATE TABLE IF NOT EXISTS accounts (
id INTEGER PRIMARY KEY AUTOINCREMENT NOT NULL,
site_id INTEGER NOT NULL,
username TEXT,
access_token TEXT NOT NULL,
api_token TEXT,
balance REAL DEFAULT 0,
balance_used REAL DEFAULT 0,
quota REAL DEFAULT 0,
unit_cost REAL,
value_score REAL DEFAULT 0,
status TEXT DEFAULT 'active',
checkin_enabled INTEGER DEFAULT true,
last_checkin_at TEXT,
last_balance_refresh TEXT,
extra_config TEXT,
is_pinned INTEGER DEFAULT false,
sort_order INTEGER DEFAULT 0,
oauth_provider TEXT,
oauth_account_key TEXT,
oauth_project_id TEXT,
created_at TEXT DEFAULT (datetime('now')),
updated_at TEXT DEFAULT (datetime('now')),
FOREIGN KEY (site_id) REFERENCES sites(id) ON DELETE CASCADE
);
CREATE INDEX IF NOT EXISTS accounts_site_id_idx
ON accounts (site_id);
CREATE INDEX IF NOT EXISTS accounts_status_idx
ON accounts (status);
CREATE INDEX IF NOT EXISTS accounts_site_status_idx
ON accounts (site_id, status);
CREATE INDEX IF NOT EXISTS accounts_oauth_provider_idx
ON accounts (oauth_provider);
CREATE INDEX IF NOT EXISTS accounts_oauth_identity_idx
ON accounts (oauth_provider, oauth_account_key, oauth_project_id);
-- ============================================================
-- DOWNSTREAM API KEYS
-- ============================================================
CREATE TABLE IF NOT EXISTS downstream_api_keys (
id INTEGER PRIMARY KEY AUTOINCREMENT NOT NULL,
name TEXT NOT NULL,
key TEXT NOT NULL,
description TEXT,
group_name TEXT,
tags TEXT,
enabled INTEGER DEFAULT true,
expires_at TEXT,
max_cost REAL,
used_cost REAL DEFAULT 0,
max_requests INTEGER,
used_requests INTEGER DEFAULT 0,
supported_models TEXT,
allowed_route_ids TEXT,
site_weight_multipliers TEXT,
excluded_site_ids TEXT,
excluded_credential_refs TEXT,
last_used_at TEXT,
user_id INTEGER REFERENCES users(id),
created_at TEXT DEFAULT (datetime('now')),
updated_at TEXT DEFAULT (datetime('now'))
);
CREATE UNIQUE INDEX IF NOT EXISTS downstream_api_keys_key_unique
ON downstream_api_keys (key);
CREATE INDEX IF NOT EXISTS downstream_api_keys_name_idx
ON downstream_api_keys (name);
CREATE INDEX IF NOT EXISTS downstream_api_keys_enabled_idx
ON downstream_api_keys (enabled);
CREATE INDEX IF NOT EXISTS downstream_api_keys_expires_at_idx
ON downstream_api_keys (expires_at);
-- ============================================================
-- SITE DISABLED MODELS
-- ============================================================
CREATE TABLE IF NOT EXISTS site_disabled_models (
id INTEGER PRIMARY KEY AUTOINCREMENT NOT NULL,
site_id INTEGER NOT NULL,
model_name TEXT NOT NULL,
created_at TEXT DEFAULT (datetime('now')),
FOREIGN KEY (site_id) REFERENCES sites(id) ON DELETE CASCADE
);
CREATE UNIQUE INDEX IF NOT EXISTS site_disabled_models_site_model_unique
ON site_disabled_models (site_id, model_name);
CREATE INDEX IF NOT EXISTS site_disabled_models_site_id_idx
ON site_disabled_models (site_id);
-- ============================================================
-- SITE API ENDPOINTS
-- ============================================================
CREATE TABLE IF NOT EXISTS site_api_endpoints (
id INTEGER PRIMARY KEY AUTOINCREMENT NOT NULL,
site_id INTEGER NOT NULL,
url TEXT NOT NULL,
enabled INTEGER DEFAULT true,
sort_order INTEGER DEFAULT 0,
cooldown_until TEXT,
last_selected_at TEXT,
last_failed_at TEXT,
last_failure_reason TEXT,
created_at TEXT DEFAULT (datetime('now')),
updated_at TEXT DEFAULT (datetime('now')),
FOREIGN KEY (site_id) REFERENCES sites(id) ON DELETE CASCADE
);
CREATE UNIQUE INDEX IF NOT EXISTS site_api_endpoints_site_url_unique
ON site_api_endpoints (site_id, url);
CREATE INDEX IF NOT EXISTS site_api_endpoints_site_enabled_sort_idx
ON site_api_endpoints (site_id, enabled, sort_order);
CREATE INDEX IF NOT EXISTS site_api_endpoints_site_cooldown_idx
ON site_api_endpoints (site_id, cooldown_until);
-- ============================================================
-- ACCOUNT TOKENS
-- ============================================================
CREATE TABLE IF NOT EXISTS account_tokens (
id INTEGER PRIMARY KEY AUTOINCREMENT NOT NULL,
account_id INTEGER NOT NULL,
name TEXT NOT NULL,
token TEXT NOT NULL,
source TEXT DEFAULT 'manual',
token_group TEXT,
value_status TEXT NOT NULL DEFAULT 'ready',
enabled INTEGER DEFAULT true,
is_default INTEGER DEFAULT false,
created_at TEXT DEFAULT (datetime('now')),
updated_at TEXT DEFAULT (datetime('now')),
FOREIGN KEY (account_id) REFERENCES accounts(id) ON DELETE CASCADE
);
CREATE INDEX IF NOT EXISTS account_tokens_account_id_idx
ON account_tokens (account_id);
CREATE INDEX IF NOT EXISTS account_tokens_account_enabled_idx
ON account_tokens (account_id, enabled);
CREATE INDEX IF NOT EXISTS account_tokens_enabled_idx
ON account_tokens (enabled);
-- ============================================================
-- CHECKIN LOGS
-- ============================================================
CREATE TABLE IF NOT EXISTS checkin_logs (
id INTEGER PRIMARY KEY AUTOINCREMENT NOT NULL,
account_id INTEGER NOT NULL,
status TEXT NOT NULL,
message TEXT,
reward TEXT,
created_at TEXT DEFAULT (datetime('now')),
FOREIGN KEY (account_id) REFERENCES accounts(id) ON DELETE CASCADE
);
CREATE INDEX IF NOT EXISTS checkin_logs_account_created_at_idx
ON checkin_logs (account_id, created_at);
CREATE INDEX IF NOT EXISTS checkin_logs_created_at_idx
ON checkin_logs (created_at);
CREATE INDEX IF NOT EXISTS checkin_logs_status_idx
ON checkin_logs (status);
-- ============================================================
-- MODEL AVAILABILITY
-- ============================================================
CREATE TABLE IF NOT EXISTS model_availability (
id INTEGER PRIMARY KEY AUTOINCREMENT NOT NULL,
account_id INTEGER NOT NULL,
model_name TEXT NOT NULL,
available INTEGER,
latency_ms INTEGER,
checked_at TEXT DEFAULT (datetime('now')),
is_manual INTEGER DEFAULT false,
FOREIGN KEY (account_id) REFERENCES accounts(id) ON DELETE CASCADE
);
CREATE UNIQUE INDEX IF NOT EXISTS model_availability_account_model_unique
ON model_availability (account_id, model_name);
CREATE INDEX IF NOT EXISTS model_availability_account_available_idx
ON model_availability (account_id, available);
CREATE INDEX IF NOT EXISTS model_availability_model_name_idx
ON model_availability (model_name);
-- ============================================================
-- TOKEN MODEL AVAILABILITY
-- ============================================================
CREATE TABLE IF NOT EXISTS token_model_availability (
id INTEGER PRIMARY KEY AUTOINCREMENT NOT NULL,
token_id INTEGER NOT NULL,
model_name TEXT NOT NULL,
available INTEGER,
latency_ms INTEGER,
checked_at TEXT DEFAULT (datetime('now')),
FOREIGN KEY (token_id) REFERENCES account_tokens(id) ON DELETE CASCADE
);
CREATE UNIQUE INDEX IF NOT EXISTS token_model_availability_token_model_unique
ON token_model_availability (token_id, model_name);
CREATE INDEX IF NOT EXISTS token_model_availability_token_available_idx
ON token_model_availability (token_id, available);
CREATE INDEX IF NOT EXISTS token_model_availability_model_name_idx
ON token_model_availability (model_name);
CREATE INDEX IF NOT EXISTS token_model_availability_available_idx
ON token_model_availability (available);
-- ============================================================
-- ROUTE CHANNELS
-- ============================================================
CREATE TABLE IF NOT EXISTS route_channels (
id INTEGER PRIMARY KEY AUTOINCREMENT NOT NULL,
route_id INTEGER NOT NULL,
account_id INTEGER NOT NULL,
token_id INTEGER,
oauth_route_unit_id INTEGER,
source_model TEXT,
priority INTEGER DEFAULT 0,
weight INTEGER DEFAULT 10,
enabled INTEGER DEFAULT true,
manual_override INTEGER DEFAULT false,
success_count INTEGER DEFAULT 0,
fail_count INTEGER DEFAULT 0,
total_latency_ms INTEGER DEFAULT 0,
total_cost REAL DEFAULT 0,
last_used_at TEXT,
last_selected_at TEXT,
last_fail_at TEXT,
consecutive_fail_count INTEGER NOT NULL DEFAULT 0,
cooldown_level INTEGER NOT NULL DEFAULT 0,
cooldown_until TEXT,
FOREIGN KEY (route_id) REFERENCES token_routes(id) ON DELETE CASCADE,
FOREIGN KEY (account_id) REFERENCES accounts(id) ON DELETE CASCADE,
FOREIGN KEY (token_id) REFERENCES account_tokens(id) ON DELETE SET NULL
);
CREATE INDEX IF NOT EXISTS route_channels_route_id_idx
ON route_channels (route_id);
CREATE INDEX IF NOT EXISTS route_channels_account_id_idx
ON route_channels (account_id);
CREATE INDEX IF NOT EXISTS route_channels_token_id_idx
ON route_channels (token_id);
CREATE INDEX IF NOT EXISTS route_channels_route_enabled_idx
ON route_channels (route_id, enabled);
CREATE INDEX IF NOT EXISTS route_channels_route_token_idx
ON route_channels (route_id, token_id);
CREATE INDEX IF NOT EXISTS route_channels_oauth_route_unit_id_idx
ON route_channels (oauth_route_unit_id);
-- ============================================================
-- ROUTE GROUP SOURCES
-- ============================================================
CREATE TABLE IF NOT EXISTS route_group_sources (
id INTEGER PRIMARY KEY AUTOINCREMENT NOT NULL,
group_route_id INTEGER NOT NULL,
source_route_id INTEGER NOT NULL,
FOREIGN KEY (group_route_id) REFERENCES token_routes(id) ON DELETE CASCADE,
FOREIGN KEY (source_route_id) REFERENCES token_routes(id) ON DELETE CASCADE
);
CREATE UNIQUE INDEX IF NOT EXISTS route_group_sources_group_source_unique
ON route_group_sources (group_route_id, source_route_id);
CREATE INDEX IF NOT EXISTS route_group_sources_source_route_id_idx
ON route_group_sources (source_route_id);
-- ============================================================
-- PROXY LOGS
-- ============================================================
CREATE TABLE IF NOT EXISTS proxy_logs (
id INTEGER PRIMARY KEY AUTOINCREMENT NOT NULL,
route_id INTEGER,
channel_id INTEGER,
account_id INTEGER,
downstream_api_key_id INTEGER,
model_requested TEXT,
model_actual TEXT,
status TEXT,
http_status INTEGER,
latency_ms INTEGER,
first_byte_latency_ms INTEGER,
prompt_tokens INTEGER,
completion_tokens INTEGER,
total_tokens INTEGER,
estimated_cost REAL,
error_message TEXT,
retry_count INTEGER DEFAULT 0,
is_stream INTEGER,
client_family TEXT,
client_app_id TEXT,
client_app_name TEXT,
client_confidence TEXT,
billing_details TEXT,
created_at TEXT DEFAULT (datetime('now'))
);
CREATE INDEX IF NOT EXISTS proxy_logs_created_at_idx
ON proxy_logs (created_at);
CREATE INDEX IF NOT EXISTS proxy_logs_account_created_at_idx
ON proxy_logs (account_id, created_at);
CREATE INDEX IF NOT EXISTS proxy_logs_status_created_at_idx
ON proxy_logs (status, created_at);
CREATE INDEX IF NOT EXISTS proxy_logs_model_actual_created_at_idx
ON proxy_logs (model_actual, created_at);
CREATE INDEX IF NOT EXISTS proxy_logs_downstream_api_key_created_at_idx
ON proxy_logs (downstream_api_key_id, created_at);
CREATE INDEX IF NOT EXISTS proxy_logs_client_app_id_created_at_idx
ON proxy_logs (client_app_id, created_at);
CREATE INDEX IF NOT EXISTS proxy_logs_client_family_created_at_idx
ON proxy_logs (client_family, created_at);
-- ============================================================
-- PROXY VIDEO TASKS
-- ============================================================
CREATE TABLE IF NOT EXISTS proxy_video_tasks (
id INTEGER PRIMARY KEY AUTOINCREMENT NOT NULL,
public_id TEXT NOT NULL,
upstream_video_id TEXT NOT NULL,
site_url TEXT NOT NULL,
token_value TEXT NOT NULL,
requested_model TEXT,
actual_model TEXT,
channel_id INTEGER,
account_id INTEGER,
status_snapshot TEXT,
upstream_response_meta TEXT,
last_upstream_status INTEGER,
last_polled_at TEXT,
created_at TEXT DEFAULT (datetime('now')),
updated_at TEXT DEFAULT (datetime('now'))
);
CREATE UNIQUE INDEX IF NOT EXISTS proxy_video_tasks_public_id_unique
ON proxy_video_tasks (public_id);
CREATE INDEX IF NOT EXISTS proxy_video_tasks_upstream_video_id_idx
ON proxy_video_tasks (upstream_video_id);
CREATE INDEX IF NOT EXISTS proxy_video_tasks_created_at_idx
ON proxy_video_tasks (created_at);
-- ============================================================
-- PROXY FILES
-- ============================================================
CREATE TABLE IF NOT EXISTS proxy_files (
id INTEGER PRIMARY KEY AUTOINCREMENT NOT NULL,
public_id TEXT NOT NULL,
owner_type TEXT NOT NULL,
owner_id TEXT NOT NULL,
filename TEXT NOT NULL,
mime_type TEXT NOT NULL,
purpose TEXT,
byte_size INTEGER NOT NULL,
sha256 TEXT NOT NULL,
content_base64 TEXT NOT NULL,
created_at TEXT DEFAULT (datetime('now')),
updated_at TEXT DEFAULT (datetime('now')),
deleted_at TEXT
);
CREATE UNIQUE INDEX IF NOT EXISTS proxy_files_public_id_unique
ON proxy_files (public_id);
CREATE INDEX IF NOT EXISTS proxy_files_owner_lookup_idx
ON proxy_files (owner_type, owner_id, deleted_at);
-- ============================================================
-- PROXY DEBUG TRACES
-- ============================================================
CREATE TABLE IF NOT EXISTS proxy_debug_traces (
id INTEGER PRIMARY KEY AUTOINCREMENT NOT NULL,
downstream_path TEXT NOT NULL,
client_kind TEXT,
session_id TEXT,
trace_hint TEXT,
requested_model TEXT,
downstream_api_key_id INTEGER,
request_headers_json TEXT,
request_body_json TEXT,
sticky_session_key TEXT,
sticky_hit_channel_id INTEGER,
selected_channel_id INTEGER,
selected_route_id INTEGER,
selected_account_id INTEGER,
selected_site_id INTEGER,
selected_site_platform TEXT,
endpoint_candidates_json TEXT,
endpoint_runtime_state_json TEXT,
decision_summary_json TEXT,
final_status TEXT,
final_http_status INTEGER,
final_upstream_path TEXT,
final_response_headers_json TEXT,
final_response_body_json TEXT,
created_at TEXT DEFAULT (datetime('now')),
updated_at TEXT DEFAULT (datetime('now'))
);
CREATE INDEX IF NOT EXISTS proxy_debug_traces_created_at_idx
ON proxy_debug_traces (created_at);
CREATE INDEX IF NOT EXISTS proxy_debug_traces_session_created_at_idx
ON proxy_debug_traces (session_id, created_at);
CREATE INDEX IF NOT EXISTS proxy_debug_traces_model_created_at_idx
ON proxy_debug_traces (requested_model, created_at);
CREATE INDEX IF NOT EXISTS proxy_debug_traces_final_status_created_at_idx
ON proxy_debug_traces (final_status, created_at);
-- ============================================================
-- PROXY DEBUG ATTEMPTS
-- ============================================================
CREATE TABLE IF NOT EXISTS proxy_debug_attempts (
id INTEGER PRIMARY KEY AUTOINCREMENT NOT NULL,
trace_id INTEGER NOT NULL,
attempt_index INTEGER NOT NULL,
endpoint TEXT NOT NULL,
request_path TEXT NOT NULL,
target_url TEXT NOT NULL,
runtime_executor TEXT,
request_headers_json TEXT,
request_body_json TEXT,
response_status INTEGER,
response_headers_json TEXT,
response_body_json TEXT,
raw_error_text TEXT,
recover_applied INTEGER DEFAULT false,
downgrade_decision INTEGER DEFAULT false,
downgrade_reason TEXT,
memory_write_json TEXT,
created_at TEXT DEFAULT (datetime('now')),
FOREIGN KEY (trace_id) REFERENCES proxy_debug_traces(id) ON DELETE CASCADE
);
CREATE UNIQUE INDEX IF NOT EXISTS proxy_debug_attempts_trace_attempt_unique
ON proxy_debug_attempts (trace_id, attempt_index);
CREATE INDEX IF NOT EXISTS proxy_debug_attempts_trace_created_at_idx
ON proxy_debug_attempts (trace_id, created_at);
-- ============================================================
-- EVENTS
-- ============================================================
CREATE TABLE IF NOT EXISTS events (
id INTEGER PRIMARY KEY AUTOINCREMENT NOT NULL,
type TEXT NOT NULL,
title TEXT NOT NULL,
message TEXT,
level TEXT NOT NULL DEFAULT 'info',
read INTEGER DEFAULT false,
related_id INTEGER,
related_type TEXT,
created_at TEXT DEFAULT (datetime('now'))
);
CREATE INDEX IF NOT EXISTS events_read_created_at_idx
ON events (read, created_at);
CREATE INDEX IF NOT EXISTS events_type_created_at_idx
ON events (type, created_at);
CREATE INDEX IF NOT EXISTS events_created_at_idx
ON events (created_at);
-- ============================================================
-- SITE ANNOUNCEMENTS
-- ============================================================
CREATE TABLE IF NOT EXISTS site_announcements (
id INTEGER PRIMARY KEY AUTOINCREMENT NOT NULL,
site_id INTEGER NOT NULL,
platform TEXT NOT NULL,
source_key TEXT NOT NULL,
title TEXT NOT NULL,
content TEXT NOT NULL,
level TEXT NOT NULL DEFAULT 'info',
source_url TEXT,
starts_at TEXT,
ends_at TEXT,
upstream_created_at TEXT,
upstream_updated_at TEXT,
first_seen_at TEXT DEFAULT (datetime('now')),
last_seen_at TEXT DEFAULT (datetime('now')),
read_at TEXT,
dismissed_at TEXT,
raw_payload TEXT,
FOREIGN KEY (site_id) REFERENCES sites(id) ON DELETE CASCADE
);
CREATE UNIQUE INDEX IF NOT EXISTS site_announcements_site_source_key_unique
ON site_announcements (site_id, source_key);
CREATE INDEX IF NOT EXISTS site_announcements_site_id_first_seen_at_idx
ON site_announcements (site_id, first_seen_at);
CREATE INDEX IF NOT EXISTS site_announcements_read_at_idx
ON site_announcements (read_at);
-- ============================================================
-- OAUTH ROUTE UNITS
-- ============================================================
CREATE TABLE IF NOT EXISTS oauth_route_units (
id INTEGER PRIMARY KEY AUTOINCREMENT NOT NULL,
site_id INTEGER NOT NULL,
provider TEXT NOT NULL,
name TEXT NOT NULL,
strategy TEXT NOT NULL DEFAULT 'round_robin',
enabled INTEGER DEFAULT true,
created_at TEXT DEFAULT (datetime('now')),
updated_at TEXT DEFAULT (datetime('now')),
FOREIGN KEY (site_id) REFERENCES sites(id) ON DELETE CASCADE
);
CREATE INDEX IF NOT EXISTS oauth_route_units_site_provider_idx
ON oauth_route_units (site_id, provider);
CREATE INDEX IF NOT EXISTS oauth_route_units_enabled_idx
ON oauth_route_units (enabled);
-- ============================================================
-- OAUTH ROUTE UNIT MEMBERS
-- ============================================================
CREATE TABLE IF NOT EXISTS oauth_route_unit_members (
id INTEGER PRIMARY KEY AUTOINCREMENT NOT NULL,
unit_id INTEGER NOT NULL,
account_id INTEGER NOT NULL,
sort_order INTEGER DEFAULT 0,
success_count INTEGER DEFAULT 0,
fail_count INTEGER DEFAULT 0,
total_latency_ms INTEGER DEFAULT 0,
total_cost REAL DEFAULT 0,
last_used_at TEXT,
last_selected_at TEXT,
last_fail_at TEXT,
consecutive_fail_count INTEGER NOT NULL DEFAULT 0,
cooldown_level INTEGER NOT NULL DEFAULT 0,
cooldown_until TEXT,
created_at TEXT DEFAULT (datetime('now')),
updated_at TEXT DEFAULT (datetime('now')),
FOREIGN KEY (unit_id) REFERENCES oauth_route_units(id) ON DELETE CASCADE,
FOREIGN KEY (account_id) REFERENCES accounts(id) ON DELETE CASCADE
);
CREATE UNIQUE INDEX IF NOT EXISTS oauth_route_unit_members_unit_account_unique
ON oauth_route_unit_members (unit_id, account_id);
CREATE UNIQUE INDEX IF NOT EXISTS oauth_route_unit_members_account_unique
ON oauth_route_unit_members (account_id);
CREATE INDEX IF NOT EXISTS oauth_route_unit_members_unit_sort_idx
ON oauth_route_unit_members (unit_id, sort_order);
CREATE INDEX IF NOT EXISTS oauth_route_unit_members_unit_cooldown_idx
ON oauth_route_unit_members (unit_id, cooldown_until);
-- ============================================================
-- SETTINGS
-- ============================================================
CREATE TABLE IF NOT EXISTS settings (
key TEXT PRIMARY KEY NOT NULL,
value TEXT
);
-- ============================================================
-- ADMIN SNAPSHOTS
-- ============================================================
CREATE TABLE IF NOT EXISTS admin_snapshots (
id INTEGER PRIMARY KEY AUTOINCREMENT NOT NULL,
namespace TEXT NOT NULL,
snapshot_key TEXT NOT NULL,
payload TEXT NOT NULL,
generated_at TEXT NOT NULL,
expires_at TEXT NOT NULL,
stale_until TEXT NOT NULL,
created_at TEXT DEFAULT (datetime('now')),
updated_at TEXT DEFAULT (datetime('now'))
);
CREATE UNIQUE INDEX IF NOT EXISTS admin_snapshots_namespace_key_unique
ON admin_snapshots (namespace, snapshot_key);
CREATE INDEX IF NOT EXISTS admin_snapshots_expires_at_idx
ON admin_snapshots (expires_at);
CREATE INDEX IF NOT EXISTS admin_snapshots_stale_until_idx
ON admin_snapshots (stale_until);
-- ============================================================
-- ANALYTICS PROJECTION CHECKPOINTS
-- ============================================================
CREATE TABLE IF NOT EXISTS analytics_projection_checkpoints (
projector_key TEXT PRIMARY KEY NOT NULL,
time_zone TEXT NOT NULL DEFAULT 'Local',
last_proxy_log_id INTEGER NOT NULL DEFAULT 0,
watermark_created_at TEXT,
recompute_from_id INTEGER,
recompute_requested_at TEXT,
recompute_reason TEXT,
recompute_started_at TEXT,
recompute_completed_at TEXT,
last_projected_at TEXT,
last_successful_at TEXT,
last_error TEXT,
lease_owner TEXT,
lease_token TEXT,
lease_expires_at TEXT,
created_at TEXT DEFAULT (datetime('now')),
updated_at TEXT DEFAULT (datetime('now'))
);
CREATE INDEX IF NOT EXISTS analytics_projection_checkpoints_recompute_from_id_idx
ON analytics_projection_checkpoints (recompute_from_id);
CREATE INDEX IF NOT EXISTS analytics_projection_checkpoints_lease_expires_at_idx
ON analytics_projection_checkpoints (lease_expires_at);
-- ============================================================
-- MODEL DAY USAGE
-- ============================================================
CREATE TABLE IF NOT EXISTS model_day_usage (
id INTEGER PRIMARY KEY AUTOINCREMENT NOT NULL,
local_day TEXT NOT NULL,
site_id INTEGER NOT NULL,
model TEXT NOT NULL,
total_calls INTEGER NOT NULL DEFAULT 0,
success_calls INTEGER NOT NULL DEFAULT 0,
failed_calls INTEGER NOT NULL DEFAULT 0,
total_tokens INTEGER NOT NULL DEFAULT 0,
total_spend REAL NOT NULL DEFAULT 0,
total_latency_ms INTEGER NOT NULL DEFAULT 0,
latency_count INTEGER NOT NULL DEFAULT 0,
created_at TEXT DEFAULT (datetime('now')),
updated_at TEXT DEFAULT (datetime('now')),
FOREIGN KEY (site_id) REFERENCES sites(id) ON DELETE CASCADE,
CONSTRAINT model_day_usage_non_negative CHECK (
total_calls >= 0
AND success_calls >= 0
AND failed_calls >= 0
AND total_tokens >= 0
AND total_spend >= 0
AND total_latency_ms >= 0
AND latency_count >= 0
)
);
CREATE UNIQUE INDEX IF NOT EXISTS model_day_usage_day_site_model_unique
ON model_day_usage (local_day, site_id, model);
CREATE INDEX IF NOT EXISTS model_day_usage_day_idx
ON model_day_usage (local_day);
CREATE INDEX IF NOT EXISTS model_day_usage_site_id_idx
ON model_day_usage (site_id);
CREATE INDEX IF NOT EXISTS model_day_usage_model_idx
ON model_day_usage (model);
-- ============================================================
-- SITE DAY USAGE
-- ============================================================
CREATE TABLE IF NOT EXISTS site_day_usage (
id INTEGER PRIMARY KEY AUTOINCREMENT NOT NULL,
local_day TEXT NOT NULL,
site_id INTEGER NOT NULL,
total_calls INTEGER NOT NULL DEFAULT 0,
success_calls INTEGER NOT NULL DEFAULT 0,
failed_calls INTEGER NOT NULL DEFAULT 0,
total_tokens INTEGER NOT NULL DEFAULT 0,
total_summary_spend REAL NOT NULL DEFAULT 0,
total_site_spend REAL NOT NULL DEFAULT 0,
total_latency_ms INTEGER NOT NULL DEFAULT 0,
latency_count INTEGER NOT NULL DEFAULT 0,
created_at TEXT DEFAULT (datetime('now')),
updated_at TEXT DEFAULT (datetime('now')),
FOREIGN KEY (site_id) REFERENCES sites(id) ON DELETE CASCADE,
CONSTRAINT site_day_usage_non_negative CHECK (
total_calls >= 0
AND success_calls >= 0
AND failed_calls >= 0
AND total_tokens >= 0
AND total_summary_spend >= 0
AND total_site_spend >= 0
AND total_latency_ms >= 0
AND latency_count >= 0
)
);
CREATE UNIQUE INDEX IF NOT EXISTS site_day_usage_day_site_unique
ON site_day_usage (local_day, site_id);
CREATE INDEX IF NOT EXISTS site_day_usage_day_idx
ON site_day_usage (local_day);
CREATE INDEX IF NOT EXISTS site_day_usage_site_id_idx
ON site_day_usage (site_id);
-- ============================================================
-- SITE HOUR USAGE
-- ============================================================
CREATE TABLE IF NOT EXISTS site_hour_usage (
id INTEGER PRIMARY KEY AUTOINCREMENT NOT NULL,
bucket_start_utc TEXT NOT NULL,
site_id INTEGER NOT NULL,
total_calls INTEGER NOT NULL DEFAULT 0,
success_calls INTEGER NOT NULL DEFAULT 0,
failed_calls INTEGER NOT NULL DEFAULT 0,
total_tokens INTEGER NOT NULL DEFAULT 0,
total_summary_spend REAL NOT NULL DEFAULT 0,
total_site_spend REAL NOT NULL DEFAULT 0,
total_latency_ms INTEGER NOT NULL DEFAULT 0,
latency_count INTEGER NOT NULL DEFAULT 0,
created_at TEXT DEFAULT (datetime('now')),
updated_at TEXT DEFAULT (datetime('now')),
FOREIGN KEY (site_id) REFERENCES sites(id) ON DELETE CASCADE,
CONSTRAINT site_hour_usage_non_negative CHECK (
total_calls >= 0
AND success_calls >= 0
AND failed_calls >= 0
AND total_tokens >= 0
AND total_summary_spend >= 0
AND total_site_spend >= 0
AND total_latency_ms >= 0
AND latency_count >= 0
)
);
CREATE UNIQUE INDEX IF NOT EXISTS site_hour_usage_hour_site_unique
ON site_hour_usage (bucket_start_utc, site_id);
CREATE INDEX IF NOT EXISTS site_hour_usage_hour_idx
ON site_hour_usage (bucket_start_utc);
CREATE INDEX IF NOT EXISTS site_hour_usage_site_id_idx
ON site_hour_usage (site_id);
migrations/20260517000001_background_tasks.sql
+24
View File
@@ -0,0 +1,24 @@
-- Background tasks tracking
CREATE TABLE IF NOT EXISTS background_tasks (
id TEXT PRIMARY KEY NOT NULL,
task_type TEXT NOT NULL,
title TEXT NOT NULL,
status TEXT NOT NULL DEFAULT 'pending',
message TEXT DEFAULT '',
error TEXT,
dedupe_key TEXT,
success_title TEXT,
failure_title TEXT,
notify_on_success INTEGER DEFAULT true,
notify_on_failure INTEGER DEFAULT true,
result_json TEXT,
progress INTEGER DEFAULT 0,
progress_total INTEGER DEFAULT 0,
created_at TEXT DEFAULT (datetime('now')),
updated_at TEXT DEFAULT (datetime('now')),
started_at TEXT,
finished_at TEXT
);
CREATE INDEX IF NOT EXISTS background_tasks_status_idx
ON background_tasks (status);
migrations/20260517000002_organizations.sql
+53
View File
@@ -0,0 +1,53 @@
-- Organizations, members, and invitations for multi-tenant support
CREATE TABLE IF NOT EXISTS organizations (
id INTEGER PRIMARY KEY AUTOINCREMENT NOT NULL,
name TEXT NOT NULL,
slug TEXT NOT NULL UNIQUE,
plan TEXT NOT NULL DEFAULT 'free',
status TEXT NOT NULL DEFAULT 'active',
created_at TEXT DEFAULT (datetime('now')),
updated_at TEXT DEFAULT (datetime('now'))
);
CREATE UNIQUE INDEX IF NOT EXISTS org_slug_idx
ON organizations (slug);
CREATE INDEX IF NOT EXISTS org_plan_idx
ON organizations (plan);
CREATE TABLE IF NOT EXISTS organization_members (
id INTEGER PRIMARY KEY AUTOINCREMENT NOT NULL,
org_id INTEGER NOT NULL REFERENCES organizations(id) ON DELETE CASCADE,
user_id INTEGER NOT NULL REFERENCES users(id) ON DELETE CASCADE,
role TEXT NOT NULL DEFAULT 'member',
status TEXT NOT NULL DEFAULT 'active',
joined_at TEXT DEFAULT (datetime('now'))
);
CREATE UNIQUE INDEX IF NOT EXISTS org_member_unique
ON organization_members (org_id, user_id);
CREATE INDEX IF NOT EXISTS org_members_org_id_idx
ON organization_members (org_id);
CREATE INDEX IF NOT EXISTS org_members_user_id_idx
ON organization_members (user_id);
CREATE TABLE IF NOT EXISTS invitations (
id INTEGER PRIMARY KEY AUTOINCREMENT NOT NULL,
org_id INTEGER NOT NULL REFERENCES organizations(id) ON DELETE CASCADE,
email TEXT NOT NULL,
token TEXT NOT NULL UNIQUE,
role TEXT NOT NULL DEFAULT 'member',
invited_by INTEGER REFERENCES users(id),
status TEXT NOT NULL DEFAULT 'pending',
expires_at TEXT NOT NULL,
created_at TEXT DEFAULT (datetime('now'))
);
CREATE UNIQUE INDEX IF NOT EXISTS invitations_token_unique
ON invitations (token);
CREATE INDEX IF NOT EXISTS invitations_status_idx
ON invitations (status);
migrations/20260518000001_usage_logs.sql
+37
View File
@@ -0,0 +1,37 @@
-- Usage tracking tables migrated from the Node.js backend.
CREATE TABLE IF NOT EXISTS usage_logs (
id INTEGER PRIMARY KEY AUTOINCREMENT,
downstream_key_id INTEGER,
model TEXT,
prompt_tokens INTEGER DEFAULT 0,
completion_tokens INTEGER DEFAULT 0,
total_tokens INTEGER DEFAULT 0,
cost REAL DEFAULT 0.0,
created_at TEXT DEFAULT (datetime('now')),
FOREIGN KEY (downstream_key_id) REFERENCES downstream_api_keys(id) ON DELETE SET NULL
);
CREATE INDEX IF NOT EXISTS usage_logs_downstream_key_created_idx
ON usage_logs (downstream_key_id, created_at);
CREATE INDEX IF NOT EXISTS usage_logs_created_idx
ON usage_logs (created_at);
CREATE TABLE IF NOT EXISTS usage_daily_snapshots (
id INTEGER PRIMARY KEY AUTOINCREMENT,
local_day TEXT NOT NULL,
downstream_key_id INTEGER,
request_count INTEGER NOT NULL DEFAULT 0,
prompt_tokens INTEGER NOT NULL DEFAULT 0,
completion_tokens INTEGER NOT NULL DEFAULT 0,
total_tokens INTEGER NOT NULL DEFAULT 0,
total_cost REAL NOT NULL DEFAULT 0.0,
created_at TEXT DEFAULT (datetime('now')),
updated_at TEXT DEFAULT (datetime('now')),
UNIQUE(local_day, downstream_key_id),
FOREIGN KEY (downstream_key_id) REFERENCES downstream_api_keys(id) ON DELETE SET NULL
);
CREATE INDEX IF NOT EXISTS usage_daily_snapshots_day_idx
ON usage_daily_snapshots (local_day);
migrations/20260522000001_user_announcements.sql
+33
View File
@@ -0,0 +1,33 @@
-- Admin-authored announcements for normal users.
CREATE TABLE IF NOT EXISTS user_announcements (
id INTEGER PRIMARY KEY AUTOINCREMENT NOT NULL,
title TEXT NOT NULL,
content TEXT NOT NULL,
level TEXT NOT NULL DEFAULT 'info',
status TEXT NOT NULL DEFAULT 'published',
audience TEXT NOT NULL DEFAULT 'all',
starts_at TEXT,
ends_at TEXT,
created_at TEXT NOT NULL DEFAULT (datetime('now')),
updated_at TEXT NOT NULL DEFAULT (datetime('now')),
published_at TEXT
);
CREATE INDEX IF NOT EXISTS user_announcements_status_created_at_idx
ON user_announcements (status, created_at);
CREATE INDEX IF NOT EXISTS user_announcements_active_window_idx
ON user_announcements (starts_at, ends_at);
CREATE TABLE IF NOT EXISTS user_announcement_reads (
announcement_id INTEGER NOT NULL,
user_id INTEGER NOT NULL,
read_at TEXT NOT NULL DEFAULT (datetime('now')),
PRIMARY KEY (announcement_id, user_id),
FOREIGN KEY (announcement_id) REFERENCES user_announcements(id) ON DELETE CASCADE,
FOREIGN KEY (user_id) REFERENCES users(id) ON DELETE CASCADE
);
CREATE INDEX IF NOT EXISTS user_announcement_reads_user_id_idx
ON user_announcement_reads (user_id);
migrations/20260522000002_workspace_assets.sql
+34
View File
@@ -0,0 +1,34 @@
-- Workspace assets: local archive for creative outputs from Picture Agent,
-- ComfyUI Agent, Video Agent and ComfyUI workspaces.
CREATE TABLE IF NOT EXISTS workspace_assets (
id INTEGER PRIMARY KEY AUTOINCREMENT,
public_id TEXT NOT NULL UNIQUE,
user_id INTEGER,
source TEXT NOT NULL,
kind TEXT NOT NULL,
title TEXT,
prompt TEXT,
model TEXT,
status TEXT NOT NULL DEFAULT 'completed',
mime_type TEXT,
file_name TEXT,
file_path TEXT,
remote_url TEXT,
thumbnail_path TEXT,
size_bytes INTEGER NOT NULL DEFAULT 0,
metadata TEXT NOT NULL DEFAULT '{}',
created_at TEXT NOT NULL DEFAULT (datetime('now')),
updated_at TEXT NOT NULL DEFAULT (datetime('now')),
deleted_at TEXT,
FOREIGN KEY(user_id) REFERENCES users(id) ON DELETE SET NULL
);
CREATE INDEX IF NOT EXISTS idx_workspace_assets_user_created
ON workspace_assets(user_id, created_at DESC);
CREATE INDEX IF NOT EXISTS idx_workspace_assets_source_created
ON workspace_assets(source, created_at DESC);
CREATE INDEX IF NOT EXISTS idx_workspace_assets_kind_created
ON workspace_assets(kind, created_at DESC);
CREATE INDEX IF NOT EXISTS idx_workspace_assets_deleted
ON workspace_assets(deleted_at);
migrations/20260523000001_workflow_studio.sql
+64
View File
@@ -0,0 +1,64 @@
-- BoosAPI Workflow Studio core tables.
CREATE TABLE IF NOT EXISTS workflows (
id INTEGER PRIMARY KEY AUTOINCREMENT,
public_id TEXT NOT NULL UNIQUE,
user_id INTEGER,
name TEXT NOT NULL,
description TEXT,
graph TEXT NOT NULL DEFAULT '{}',
is_template INTEGER NOT NULL DEFAULT 0,
visibility TEXT NOT NULL DEFAULT 'private',
created_at TEXT NOT NULL DEFAULT (datetime('now')),
updated_at TEXT NOT NULL DEFAULT (datetime('now')),
deleted_at TEXT,
FOREIGN KEY(user_id) REFERENCES users(id) ON DELETE SET NULL
);
CREATE INDEX IF NOT EXISTS idx_workflows_user_updated
ON workflows(user_id, updated_at DESC);
CREATE INDEX IF NOT EXISTS idx_workflows_visibility
ON workflows(visibility);
CREATE INDEX IF NOT EXISTS idx_workflows_deleted
ON workflows(deleted_at);
CREATE TABLE IF NOT EXISTS workflow_runs (
id INTEGER PRIMARY KEY AUTOINCREMENT,
public_id TEXT NOT NULL UNIQUE,
workflow_id INTEGER NOT NULL,
user_id INTEGER,
status TEXT NOT NULL,
input_overrides TEXT NOT NULL DEFAULT '{}',
final_outputs TEXT,
error_message TEXT,
started_at TEXT,
completed_at TEXT,
created_at TEXT NOT NULL DEFAULT (datetime('now')),
FOREIGN KEY(workflow_id) REFERENCES workflows(id) ON DELETE CASCADE,
FOREIGN KEY(user_id) REFERENCES users(id) ON DELETE SET NULL
);
CREATE INDEX IF NOT EXISTS idx_workflow_runs_workflow_created
ON workflow_runs(workflow_id, created_at DESC);
CREATE INDEX IF NOT EXISTS idx_workflow_runs_user_created
ON workflow_runs(user_id, created_at DESC);
CREATE INDEX IF NOT EXISTS idx_workflow_runs_status
ON workflow_runs(status);
CREATE TABLE IF NOT EXISTS workflow_node_runs (
id INTEGER PRIMARY KEY AUTOINCREMENT,
run_id INTEGER NOT NULL,
node_id TEXT NOT NULL,
node_type TEXT NOT NULL,
status TEXT NOT NULL,
inputs TEXT NOT NULL DEFAULT '{}',
outputs TEXT,
error_message TEXT,
started_at TEXT,
completed_at TEXT,
created_at TEXT NOT NULL DEFAULT (datetime('now')),
FOREIGN KEY(run_id) REFERENCES workflow_runs(id) ON DELETE CASCADE
);
CREATE INDEX IF NOT EXISTS idx_workflow_node_runs_run
ON workflow_node_runs(run_id, id);
migrations/20260606000001_proxy_log_content.sql
+3
View File
@@ -0,0 +1,3 @@
ALTER TABLE proxy_logs ADD COLUMN content_summary TEXT;
ALTER TABLE proxy_logs ADD COLUMN request_content TEXT;
ALTER TABLE proxy_logs ADD COLUMN response_content TEXT;
migrations/20260606000002_performance_projections.sql
+51
View File
@@ -0,0 +1,51 @@
-- Performance-oriented projections and indexes for logs/workspace views.
CREATE INDEX IF NOT EXISTS proxy_logs_key_created_status_idx
ON proxy_logs (downstream_api_key_id, created_at DESC, status);
CREATE INDEX IF NOT EXISTS proxy_logs_key_model_created_idx
ON proxy_logs (downstream_api_key_id, model_actual, created_at DESC);
CREATE INDEX IF NOT EXISTS proxy_logs_content_summary_idx
ON proxy_logs (content_summary);
CREATE INDEX IF NOT EXISTS workspace_assets_user_output_created_idx
ON workspace_assets (
user_id,
status,
deleted_at,
source,
kind,
created_at DESC
);
CREATE INDEX IF NOT EXISTS workspace_assets_output_role_created_idx
ON workspace_assets (
json_extract(metadata, '$.workspaceAsset.role'),
created_at DESC
);
CREATE INDEX IF NOT EXISTS workspace_assets_workflow_output_created_idx
ON workspace_assets (
json_extract(metadata, '$.workflowUi.type'),
created_at DESC
);
CREATE TABLE IF NOT EXISTS workspace_asset_daily (
local_day TEXT NOT NULL,
user_id INTEGER NOT NULL DEFAULT 0,
source TEXT NOT NULL,
kind TEXT NOT NULL,
asset_count INTEGER NOT NULL DEFAULT 0,
local_file_count INTEGER NOT NULL DEFAULT 0,
total_size_bytes INTEGER NOT NULL DEFAULT 0,
created_at TEXT DEFAULT (datetime('now')),
updated_at TEXT DEFAULT (datetime('now')),
UNIQUE(local_day, user_id, source, kind)
);
CREATE INDEX IF NOT EXISTS workspace_asset_daily_user_day_idx
ON workspace_asset_daily (user_id, local_day DESC);
CREATE INDEX IF NOT EXISTS workspace_asset_daily_source_day_idx
ON workspace_asset_daily (source, local_day DESC);

Some files were not shown because too many files have changed in this diff Show More