From 17553e2f8fdb075bd3bad71df74a8496dd2452fa Mon Sep 17 00:00:00 2001
From: eust-w
Date: Tue, 27 Oct 2026 23:19:08 +0800
Subject: [PATCH] =?UTF-8?q?=E2=9C=A8=20Let=20a=20person=20widen=20a=20fron?=
=?UTF-8?q?tend-only=20wish=20to=20backend=20code?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit
When the agent of a frontend-only wish asks to change backend code, or keeps
changing it until the repair rounds run out, the run details offer "改为前端和
后端并继续". It answers the wish with allowBackend: the run may change backend
code from the new requirement revision on, the agent reads that the scope
changed, and the timeline records who widened it. Whether a backend change needs
a review still depends on the submitter's backend permission. Only an answer to
a frontend-only wish accepts the flag.
Co-Authored-By: Claude Opus 5.5
---
apps/api/src/domain/control-plane.ts | 36 ++++++++++++++----
apps/web/src/app/globals.css | 13 +++++++
apps/web/src/features/runs.tsx | 57 +++++++++++++++++++++++++++-
apps/web/src/lib/events.ts | 1 +
docs/architecture.md | 2 +-
docs/user-manual.md | 10 ++---
packages/contracts/src/index.ts | 2 +
tests/local-loop.test.ts | 44 +++++++++++++++++++++
8 files changed, 150 insertions(+), 15 deletions(-)
diff --git a/apps/api/src/domain/control-plane.ts b/apps/api/src/domain/control-plane.ts
index 6787068..0bfdf1e 100644
--- a/apps/api/src/domain/control-plane.ts
+++ b/apps/api/src/domain/control-plane.ts
@@ -472,9 +472,15 @@ export class ControlPlane {
return this.store.transaction(actor.tenantId, async tx => {
const run = await must(tx, 'run', id);
const project = await projectAccess(tx, actor, run.projectId);
- return idempotent(tx, `command:${actor.userId}:${id}:${key}`, data, () =>
- this.applyCommand(tx, run, project, data),
- );
+ return idempotent(tx, `command:${actor.userId}:${id}:${key}`, data, async () => {
+ const result = await this.applyCommand(tx, run, project, data);
+ if (data.allowBackend)
+ await tx.event(id, 'run.scope', 'The wish may change backend code from now on.', {
+ frontendOnly: false,
+ changedBy: actor.userId,
+ });
+ return result;
+ });
});
}
/**
@@ -485,10 +491,21 @@ export class ControlPlane {
tx: Transaction,
run: Run,
project: Project,
- data: { action: 'pause' | 'resume' | 'cancel' | 'answer'; message?: string; acceptanceCriteria?: string[] },
+ data: {
+ action: 'pause' | 'resume' | 'cancel' | 'answer';
+ message?: string;
+ acceptanceCriteria?: string[];
+ allowBackend?: true;
+ },
): Promise {
const id = run.id;
if (terminal(run)) throw new DomainError('TERMINAL_RUN', 'Submit a new wish to change a completed task');
+ if (data.allowBackend && (data.action !== 'answer' || !run.frontendOnly))
+ throw new DomainError(
+ 'SCOPE_UNCHANGED',
+ 'Only an answer to a frontend-only wish can let it change backend code',
+ 400,
+ );
const executing = run.status === 'running' && run.lease && Date.parse(run.lease.expiresAt) > Date.now();
if (data.action === 'resume' && (run.status === 'queued' || executing)) {
if (run.pauseRequestedAt)
@@ -514,7 +531,11 @@ export class ControlPlane {
run = touch(run);
run.pauseRequestedAt = undefined;
run.lease = run.lease ? { ...run.lease, token: run.lease.token + 1, expiresAt: now() } : undefined;
- let message = data.message ? redact(data.message) : `Run ${data.action} requested.`;
+ // Letting a frontend-only wish change backend code is part of the answer the agent reads.
+ const answer = [data.allowBackend ? '代码范围改为前端和后端:这个愿望可以修改后端代码。' : '', data.message ?? '']
+ .filter(Boolean)
+ .join('\n');
+ let message = answer ? redact(answer) : `Run ${data.action} requested.`;
if (data.action === 'cancel') {
run.status = 'canceled';
if (!run.providerProxyActiveRequest) run.reservedTokens = 0;
@@ -524,10 +545,11 @@ export class ControlPlane {
clearWaiting(run);
} else {
if (data.action === 'answer') {
- if (!data.message) throw new DomainError('ANSWER_REQUIRED', 'Provide the additional requirement', 400);
+ if (!answer) throw new DomainError('ANSWER_REQUIRED', 'Provide the additional requirement', 400);
const wish = touch(await must(tx, 'wish', run.wishId));
wish.revision += 1;
- wish.goal = `${wish.goal}\n\n${data.message}`;
+ wish.goal = `${wish.goal}\n\n${answer}`;
+ if (data.allowBackend) run.frontendOnly = false;
if (data.acceptanceCriteria) wish.acceptanceCriteria = data.acceptanceCriteria;
await tx.put('wish', wish);
run.revision = wish.revision;
diff --git a/apps/web/src/app/globals.css b/apps/web/src/app/globals.css
index 09d51c8..721cc8b 100644
--- a/apps/web/src/app/globals.css
+++ b/apps/web/src/app/globals.css
@@ -2982,3 +2982,16 @@ ul.criteria-choices {
line-height: 1.6;
color: var(--muted);
}
+.scope-unlock {
+ margin: 0 22px 15px;
+ padding: 12px 14px;
+ border: 1px solid var(--border);
+ border-radius: var(--radius);
+ background: #f6f9fb;
+}
+.scope-unlock p {
+ margin: 0 0 10px;
+ font-size: 12px;
+ line-height: 1.7;
+ color: var(--muted);
+}
diff --git a/apps/web/src/features/runs.tsx b/apps/web/src/features/runs.tsx
index 1a3c502..cfad482 100644
--- a/apps/web/src/features/runs.tsx
+++ b/apps/web/src/features/runs.tsx
@@ -9,6 +9,7 @@ import {
ChevronRight,
FileCheck2,
GitBranch,
+ LockOpen,
Pause,
Play,
Plus,
@@ -753,6 +754,7 @@ export function RunDetailView({ id }: { id: string }) {
const [error, setError] = useState('');
const [answer, setAnswer] = useState('');
const [confirmCancel, setConfirmCancel] = useState(false);
+ const [confirmScope, setConfirmScope] = useState(false);
const run = runResource.data;
useEffect(() => {
if (!run || !['running', 'queued', 'waiting'].includes(run.status)) return;
@@ -765,13 +767,14 @@ export function RunDetailView({ id }: { id: string }) {
source.addEventListener('run', update);
return () => source.close();
}, [id, run?.status]);
- async function command(action: string, message?: string) {
+ async function command(action: string, message?: string, extra: { allowBackend?: true } = {}) {
setBusy(true);
setError('');
try {
- await mutateApi(`/runs/${id}/commands`, { action, message });
+ await mutateApi(`/runs/${id}/commands`, { action, ...(message?.trim() ? { message } : {}), ...extra });
setAnswer('');
setConfirmCancel(false);
+ setConfirmScope(false);
await Promise.all([runResource.mutate(), events.mutate()]);
} catch (error) {
setError(messageOf(error));
@@ -791,6 +794,14 @@ export function RunDetailView({ id }: { id: string }) {
const budgetExhausted =
(run.usedTokens ?? 0) >= (run.budget.maxTokens ?? 0) ||
(run.activeMilliseconds ?? 0) >= (run.budget.maxMinutes ?? 0) * 60_000;
+ // A frontend-only wish whose agent asked to change backend code, or kept changing it.
+ const backendWanted =
+ run.status === 'waiting' &&
+ run.frontendOnly === true &&
+ (run.waitingReason === 'clarification' ||
+ (run.waitingReason === 'repair_exhausted' && run.lastFailure?.kind === 'scope')) &&
+ identity.data?.kind === 'human' &&
+ ['owner', 'admin', 'developer'].includes(identity.data.role);
const canUpdateBudget =
identity.data?.kind === 'human' &&
['owner', 'admin'].includes(identity.data.role) &&
@@ -887,6 +898,17 @@ export function RunDetailView({ id }: { id: string }) {
{waitingLink.label}
) : null}
+ {backendWanted ? (
+
+
+ 这个愿望只能改前端。确实要改后端时,可以放开代码范围:之后可以改后端代码,运行从规划重新开始;改到后端时要不要审核,仍按提交人的后端权限决定。
+
+
+
+ ) : null}
如需修改目标,可在下面补充需求;补充会创建新的需求版本并重新验证。
补充或修改需求
@@ -1113,6 +1135,37 @@ export function RunDetailView({ id }: { id: string }) {
) : null}
+ {confirmScope ? (
+ setConfirmScope(false)}
+ >
+
+ {run.waitingReason === 'clarification' && run.waitingDetail ? (
+
{run.waitingDetail}
+ ) : null}
+
+
+
+
+
+
+
+
+
+ ) : null}
{confirmCancel ? (
= {
'run.resume': '继续',
'run.cancel': '取消',
'run.answer': '补充需求',
+ 'run.scope': '代码范围改为前端和后端',
'run.repair': '修复轮',
'run.succeeded': '完成',
'run.budget.updated': '预算调整',
diff --git a/docs/architecture.md b/docs/architecture.md
index f298102..cdd8f0a 100644
--- a/docs/architecture.md
+++ b/docs/architecture.md
@@ -207,7 +207,7 @@ sequenceDiagram
- 执行器的进度(消息、命令、文件变更、用量)规范化为事件,经 `/internal/runs/:id/events` 写入并通过 SSE 推送。Claude Code 与 CodeBuddy 只在会话正常结束时报告总用量;会话被暂停、取消或超时打断时,按会话流中每次模型响应自带的用量估算(同一响应只计一次),在时间线上标为估算,照常计入预算。最后一次响应的输出 token 可能少计。
- 基础设施类失败(依赖安装失败、沙箱无法启动、Git 网络错误)记为 `infrastructure` 等待,不触发修复。验证命令自身超时(退出码 124)视为测试失败,进入修复。例外:检查点改动了依赖清单(`package.json`、`go.mod`、锁文件等)之后安装失败、且输出不像网络或仓库故障时,按一轮修复处理,失败类型为 `install`;修复轮中安装仍失败也照常启动执行器,并把安装输出交给它,否则执行器每次都会先装同样的坏清单,Agent 永远没有机会改。
- 执行器失败或被暂停时,已完成的工作仍会导出为检查点,继续时从该检查点恢复,而不是从头开始。
-- **代码范围**:愿望可以声明只改前端(`frontendOnly`)。执行器把项目的后端路径规则(`codeReview.paths` 减去 `exceptPaths`)写进提示词;verifier 在运行任何检查之前比较检查点的改动,改到后端路径时记一条失败的验证证据(`backendPaths`,不含命令),失败类型为 `scope`,按一轮修复处理。修复轮开始前执行器用 `git checkout -- :(literal)` 恢复这些文件、删掉新建的(Agent 默认只有读写文件的工具,取不回原内容也删不了文件),提示词告诉 Agent 只改前端重做。控制面另有一道防线:只改前端的运行请求代码审核时若带后端路径,直接拒绝(`FRONTEND_ONLY`),绝不集成。改动路径用 `git diff --no-renames` 计算,挪动的文件在新旧两个位置都算改到,代码审核和代码范围都不会被「挪到前端目录」绕过。
+- **代码范围**:愿望可以声明只改前端(`frontendOnly`)。执行器把项目的后端路径规则(`codeReview.paths` 减去 `exceptPaths`)写进提示词;verifier 在运行任何检查之前比较检查点的改动,改到后端路径时记一条失败的验证证据(`backendPaths`,不含命令),失败类型为 `scope`,按一轮修复处理。修复轮开始前执行器用 `git checkout -- :(literal)` 恢复这些文件、删掉新建的(Agent 默认只有读写文件的工具,取不回原内容也删不了文件),提示词告诉 Agent 只改前端重做。控制面另有一道防线:只改前端的运行请求代码审核时若带后端路径,直接拒绝(`FRONTEND_ONLY`),绝不集成。等待中的只改前端运行可以由人放开:补充需求时带 `allowBackend: true`,控制面清除 `frontendOnly`、把「代码范围改为前端和后端」写进新的需求版本,并记 `run.scope` 事件(含操作人);只有回答只改前端的运行时才接受这个参数(否则 `SCOPE_UNCHANGED`)。改动路径用 `git diff --no-renames` 计算,挪动的文件在新旧两个位置都算改到,代码审核和代码范围都不会被「挪到前端目录」绕过。
### 4.3 集成与交付
diff --git a/docs/user-manual.md b/docs/user-manual.md
index 8b2964d..420a41a 100644
--- a/docs/user-manual.md
+++ b/docs/user-manual.md
@@ -204,7 +204,7 @@
|---|---|
| 项目空间 | 选择项目 |
| 你的愿望 | 必填,8~20000 字。第一行写目标,可以再写「范围:」「不改:」各一行;细节写进验收标准,不需要预先拆分技术步骤 |
-| 代码范围 | 项目划出了后端代码时才显示,默认「只改前端」。**只改前端**:只能改项目放行的路径(POC 是 `src/`、`tests/frontend/`、`**/*.md`),Agent 一开始就被告知;改到后端代码时不运行检查,平台在下一轮开始前把这些文件恢复原样(新建的删掉),让 Agent 只改前端重做,算一轮修复。**前端和后端**:可以改后端;你有这个项目的后端权限时验证通过就合入,没有时先等代码审核。选项下面会写明你有没有后端权限 |
+| 代码范围 | 项目划出了后端代码时才显示,默认「只改前端」。**只改前端**:只能改项目放行的路径(POC 是 `src/`、`tests/frontend/`、`**/*.md`),Agent 一开始就被告知,做不到时会停下来提问(之后可以在运行详情放开,见 4.5);改到后端代码时不运行检查,平台在下一轮开始前把这些文件恢复原样(新建的删掉),让 Agent 只改前端重做,算一轮修复。**前端和后端**:可以改后端;你有这个项目的后端权限时验证通过就合入,没有时先等代码审核。选项下面会写明你有没有后端权限 |
| 起点 | 默认是目标分支的最新代码;平台托管仓库的项目可以选从 IDE 推送的分支,验证通过后一并合入。POC 只能从 `poc` 开始 |
| 验收标准 | 必填,每行一条,最多 30 条 |
| 执行器 | 只列出这台部署能用的执行器;POC 只有 Claude Code |
@@ -239,7 +239,7 @@
- 「取消运行」会弹出确认框「取消本次运行」,选「确认取消」才执行,选「保留运行」放弃。
- 预算已经用完时,「继续」是灰的,需要先调整预算。
-4. **等待说明**(仅等待处理时):原因的中文标题、后端给出的具体说明(多为英文)、该怎么做,有时附带链接(如「管理执行器」「去审批」)。下面可以展开「**补充或修改需求**」,写补充说明或回答问题后点「发送补充」:这会产生新的需求版本,运行从规划阶段重新开始。这个表单只在等待处理时出现,只能写文字说明,不能在这里改验收标准。
+4. **等待说明**(仅等待处理时):原因的中文标题、后端给出的具体说明(多为英文)、该怎么做,有时附带链接(如「管理执行器」「去审批」)。下面可以展开「**补充或修改需求**」,写补充说明或回答问题后点「发送补充」:这会产生新的需求版本,运行从规划阶段重新开始。这个表单只在等待处理时出现,只能写文字说明,不能在这里改验收标准。只改前端的愿望停在「执行器需要你的补充」、或者因为一直改到后端而用完了修复轮时,这里还有「**改为前端和后端并继续**」:确认后这个愿望可以改后端代码,运行带着这个决定从规划阶段重新开始(需求版本加一),确认框里可以顺便回答 Agent 的其他问题;时间线记一条「代码范围改为前端和后端」。改到后端时要不要审核,仍按提交人的后端权限决定。所有者、管理员和开发者可以操作。
5. **代码审核**(仅等待代码审核时):列出改到的后端代码和提交人,「代码变更」链接跳到完整改动。所有者或管理员勾选「我已查看「代码变更」里的全部改动」后可以「批准合入」;或写下审核意见后「驳回并说明」。批准后运行自动继续合入,不再重复检查;驳回后意见作为补充需求交给执行器再改一轮,改完会再次等待审核。其他角色只能看到「等待所有者或管理员审核」。
6. **运行预算**(仅 Owner/Admin,且运行处于等待处理或已暂停时):显示已用 Token 和已执行时间,展开「调整预算」可以改 Token 上限(最多 200 万)、时间上限(最多 180 分钟)、修复轮次上限(最多 3),点「保存预算」。保存不会自动继续,还要再点「继续」。
7. **交付结果**:部署验收通过后显示「访问应用 ↗」;未配置交付的项目显示合入的提交。
@@ -340,7 +340,7 @@
- **写具体的结果**,不写模糊的方向。✗「优化一下下载功能」;✓「下载文件名要包含数据集类型,例如 `xxx-episode.zip`」。
- **点明位置**:知道在哪个文件、哪个函数时直接写上,Agent 会少走弯路。
- **写清边界**:「只加测试,不修改 `src/` 下的代码」「不要改接口返回格式」这类限制非常有用。
-- **选对代码范围**:只动页面、样式、前端测试和文档的愿望选「只改前端」,平台会保证它碰不到后端;需要改接口、数据库、服务端逻辑时选「前端和后端」。拿不准时先选只改前端:Agent 发现必须改后端时会停下来提问,你再改选重新提交。
+- **选对代码范围**:只动页面、样式、前端测试和文档的愿望选「只改前端」,平台会保证它碰不到后端;需要改接口、数据库、服务端逻辑时选「前端和后端」。拿不准时先选只改前端:Agent 发现必须改后端时会停下来提问,你确认需要的话在运行详情点「改为前端和后端并继续」。
- **一个愿望只做一件事**:大需求拆成几个小愿望,每个都能独立验证、独立上线,出问题也容易定位。
### 5.2 验收标准:写成能检查的句子
@@ -474,9 +474,9 @@ POC 打开了 Seatbelt 沙箱,受保护检查在 macOS 沙箱里运行:读
| 执行环境未就绪 | 没能启动执行进程 | 系统会自动重试;维护者恢复服务后也可以点「继续」 |
| 没有可用的执行进程 | 执行进程没有按时接手 | 点「继续」,系统以新代次重新派发 |
| 预算已用完 | token 或时长用完 | Owner/Admin 在「运行预算」里调整后点「继续」 |
-| 执行器需要你的补充 | Agent 动手前提了问题 | 展开「补充或修改需求」回答,运行从规划阶段继续(这时没有「继续」按钮) |
+| 执行器需要你的补充 | Agent 动手前提了问题 | 展开「补充或修改需求」回答,运行从规划阶段继续(这时没有「继续」按钮)。只改前端的愿望问能不能改后端时,点「改为前端和后端并继续」 |
| 缺少验证配置 | 项目没配受保护检查 | 在项目设置里配置验证命令后点「继续」 |
-| 修复轮数已用完,验证仍未通过 | 修了几轮还是没过;或者只改前端的愿望几轮下来还是要改后端(说明里列出后端文件) | 看「验证证据」里的失败输出;点「继续」再修一轮,或补充需求,或取消。确实需要改后端时取消,改选「前端和后端」重新提交 |
+| 修复轮数已用完,验证仍未通过 | 修了几轮还是没过;或者只改前端的愿望几轮下来还是要改后端(说明里列出后端文件) | 看「验证证据」里的失败输出;点「继续」再修一轮,或补充需求,或取消。确实需要改后端时点「改为前端和后端并继续」 |
| 基础设施故障 | 依赖安装、网络、集群连接、Git 访问等出错,不消耗修复轮数 | 排除问题(可以先让维护者跑 `doctor`)后点「继续」 |
| 执行器调用失败 | 调用模型失败,已完成的工作已保存 | 确认执行器可用后点「继续」 |
| 需要人工确认 | 某个外部操作结果未知 | 查看「阶段事件」确认实际情况,再「继续」或取消 |
diff --git a/packages/contracts/src/index.ts b/packages/contracts/src/index.ts
index 4862f9f..b2a063d 100644
--- a/packages/contracts/src/index.ts
+++ b/packages/contracts/src/index.ts
@@ -446,6 +446,8 @@ export const commandInput = z
action: z.enum(['pause', 'resume', 'cancel', 'answer']),
message: text.max(20000).optional(),
acceptanceCriteria: z.array(text.max(2000)).min(1).max(30).optional(),
+ /** With an answer: the frontend-only wish may change backend code from now on. */
+ allowBackend: z.literal(true).optional(),
})
.strict();
export const environmentInput = z
diff --git a/tests/local-loop.test.ts b/tests/local-loop.test.ts
index 1acdc79..776b43f 100644
--- a/tests/local-loop.test.ts
+++ b/tests/local-loop.test.ts
@@ -1202,6 +1202,50 @@ describe('local main loop', () => {
expect(await services.control.codeReview(owner, runId)).toBeNull();
});
+ it('lets an answer widen a frontend-only wish to backend code once the agent asks for it', async () => {
+ const project = await createProject();
+ await store.transaction(TENANT, async tx => {
+ const current = (await tx.get('project', project.id))!;
+ await tx.put('project', {
+ ...current,
+ codeReview: { paths: ['**'], exceptPaths: ['greeting.txt'], trustedMembers: [owner.userId] },
+ });
+ });
+ const runId = await submit(project.id, 'Greet and log it on the server', 'wish-frontend-0002', {
+ frontendOnly: true,
+ });
+ const asked = await provision(
+ runId,
+ async () => 'Logging needs server.txt, which is backend code.\n\nQUESTIONS:\n- May this wish change server.txt?',
+ );
+ expect(await drive(asked)).toMatchObject({ status: 'waiting', reason: 'clarification' });
+ expect(prompts.at(-1)).toContain('change no files and ask instead');
+ // Only an answer to a frontend-only wish widens it.
+ await expect(
+ services.control.command(owner, runId, { action: 'resume', allowBackend: true }, 'scope-resume-0001'),
+ ).rejects.toMatchObject({ code: 'SCOPE_UNCHANGED' });
+ await services.control.command(owner, runId, { action: 'answer', allowBackend: true }, 'scope-answer-0001');
+ const widened = await services.control.run(owner, runId);
+ expect(widened).toMatchObject({ frontendOnly: false, revision: 2, status: 'queued', stage: 'plan' });
+ expect(widened.goal).toContain('代码范围改为前端和后端:这个愿望可以修改后端代码。');
+ const scoped = (await services.control.events(owner, runId)).find(event => event.type === 'run.scope');
+ expect(scoped).toMatchObject({ data: { frontendOnly: false, changedBy: owner.userId } });
+ await expect(
+ services.control.command(owner, runId, { action: 'answer', allowBackend: true }, 'scope-answer-0002'),
+ ).rejects.toMatchObject({ code: 'SCOPE_UNCHANGED' });
+ await release(runId, asked.generation);
+ const answered = await provision(runId, async start => {
+ await writeFile(path.join(start.workspace, 'server.txt'), 'log greetings\n');
+ return writeGreeting('hello world', 'Greeted and logged on the server.')(start);
+ });
+ expect(await drive(answered)).toEqual({ status: 'complete' });
+ expect(prompts.at(-1)).not.toContain('This wish may change only frontend code');
+ expect(prompts.at(-1)).toContain('代码范围改为前端和后端');
+ // The submitter may change backend code, so it merged without a review.
+ expect(await git(remote, 'show', 'main:server.txt')).toBe('log greetings');
+ expect(await services.control.codeReview(owner, runId)).toBeNull();
+ });
+
it('hands a rejected change back to the agent with the reviewer’s comment', async () => {
const project = await createProject();
await holdForReview(project.id, ['*.txt']);