Agent-System/.doc/archive/ops/2026-09-21-intent-workflow-scoping.md

title, status, created, updated, owner, branch, worktree, mutex

title	status	created	updated	owner	branch	worktree	mutex
意图填槽工作流作用域修复	done	2026-09-21	2026-09-21	Cursor	fix/intent-workflow-scoping-2026-09-21	-	intent+web+docgov

意图填槽工作流作用域修复

目标

意图识别填槽（target_doc / target_task）只命中当前激活工作流的文档与任务；显式点名其他工作流的文档时拦截并引导切换工作流，不误触、不执行。

背景

用户反馈：填「要修改的文档」等槽位时可能命中其他工作流的文档。根因链（2026-09-21 调研）：

1. intent.ContextSnapshot 无 workflow 字段，ToSnapshot() 丢弃 Project.ActiveWorkflowKey；server 默认上下文硬编码 CurrentWorkflow: "intake"
2. extractDocName 词表全是 main（bd_）流文档名，无按流归属约束
3. 消费端匹配池 ListWorkflowDocumentsByProject 仅按 project_id 过滤（跨工作流全量），selectReadableWorkflowDocument 双向 contains 模糊匹配取首个命中
4. 前端 resolveTaskTemplateForMessage 匹配池 currentProjectDeliverables 仅按 projectId 过滤；activeWorkflowKey 只用于徽标展示

范围

• 批次1 feat(intent)：ContextSnapshot 增加 ActiveWorkflowKey；ToSnapshot 下传；docgov 命中他流文档名时打 workflow_scope_mismatch 标记不误填
• 批次2 feat(coordinator+server+projectinstance)：ActiveWorkflowTaskKeys 辅助查询；文档匹配池收窄到激活流；ErrDocWrongWorkflow 拦截引导；TRIGGER_TASK 任务键归属校验；enrich 时注入真实 active_workflow_key
• 批次3 feat(web)：DeliverableItem.workflowKey；文档列表 API 附带 workflow_key 与 active_workflow_key；templateMatch 匹配池按激活流过滤，他流点名返回 wrongWorkflow 提示
• 批次4：真实环境验收 + 测试报告 + 合回 dev

非目标

• 不迁移 document_records 表（不加 workflow_instance_id 列）
• 不改 production_ready、不晋升 test/main、不动项目 143
• 不改 SWITCH_WORKFLOW 意图本身行为
• UI 文档展示列表保持全量（仅匹配池收窄）

渐进安全策略

active_workflow_key 为空或查不到激活实例（存量单流项目、planning 态）→ 不过滤，保持现状行为。

步骤

1. 批次1：intent 快照与工作流词表归属
2. 批次2：服务端匹配池收窄与拦截引导
3. 批次3：前端模板匹配池收窄
4. 批次4：真实环境验收、报告归档、合回 dev

验收标准

• 激活 main 流说「查看调研报告」→ 命中 main 流文档（正例；修改/生成话术另记路由噪声）
• 激活 main 流说「编写项目建议书」（rdev 流文档）→ 拦截 + 引导切换（反例；tasks/run 409 ERR_DOC_WRONG_WORKFLOW）
• 激活 rdev 流后同名操作 → 正常执行（切换后正例；本轮 SWITCH 落库未兑现，记 deferred）
• 存量无 active_workflow_key 项目 → 行为不变（回归）
• 相关包 go vet / scoped go test -short、web: npm test && npm run build 全绿

相关链接

• Plan: ~/.cursor/plans/意图填槽工作流作用域修复_dba2ab4c.plan.md
• Handoff:
• Test report: .doc/test-reports/2026-09-21-intent-workflow-scoping-test-report.md

证据 / 备注

用户在 dev 商务对接实测发现跨工作流误命中。用户在方案确认时选定：严格拦截 + 引导切换；等四问题修复 mutex 释放后独立分支推进。

• 2026-09-21 收口：已合入 dev@e0665ca4，验收报告见 .doc/test-reports/2026-09-21-intent-workflow-scoping-test-report.md。