X-Financial/document/development/小财管家/TODO.md

小财管家 TODO

阶段一：调研与契约

• 盘点首页输入框、工作台弹窗、会话路由和本体字段注册表。[CONCEPT: 背景与问题] 证据：已确认 PersonalWorkbench.vue、useAppShell.js、TravelReimbursementCreateView.vue、ontology_field_registry.py。
• 定义第一版只覆盖申请助手和报销助手，不引入 LangChain，但外层意图识别使用大模型 function calling。[CONCEPT: 目标与非目标] 证据：CONCEPT.md 已明确 MVP 边界和 function calling 主链路。
• 明确小财管家业务字段必须走 ontology canonical fields，编排字段不得进入业务本体。[CONCEPT: 本体字段约束] 证据：CONCEPT.md 已列出 canonical 字段与编排态字段。

阶段二：后端规划服务

• 新增 schemas/steward.py，定义计划请求、任务、附件归集、确认动作和响应模型。[CONCEPT: 后端] 证据：StewardPlanRequest、StewardTask、StewardAttachmentGroup、StewardConfirmationAction 已新增。
• 扩展 services/runtime_chat.py，支持 OpenAI-compatible / Azure OpenAI 的 tools 与 tool_choice function calling。[CONCEPT: 后端] 证据：新增 complete_with_tool_call、RuntimeChatToolCall 和工具调用解析。
• 新增 services/steward_intent_agent.py，定义 submit_steward_intent_plan function schema 并调用系统主/备模型。[CONCEPT: 任务识别与拆分] 证据：模型调用入口已从 StewardPlannerService 注入。
• 新增 services/steward_model_plan_builder.py，将模型工具参数转换为服务端可校验计划。[CONCEPT: 后端] 证据：模型返回后仍会校验任务类型、canonical 字段和附件名。
• 改造 services/steward_planner.py，实现大模型 function calling 优先、规则规划兜底。[CONCEPT: 任务识别与拆分] 证据：planning_source 区分 llm_function_call 与 rule_fallback。
• 新增 api/v1/endpoints/steward.py，提供 POST /steward/plans。[CONCEPT: 后端] 证据：容器内接口 smoke 返回 task_count=3。
• 新增 POST /steward/plans/stream，以 NDJSON 返回 thinking 和最终 plan 事件。[CONCEPT: 流式过程摘要] 证据：真实接口 smoke 返回事件序列 thinking,thinking,thinking,thinking,plan。
• 调整 POST /steward/plans/stream，确保模型 function calling 完成前先返回首个 thinking 事件。[CONCEPT: 流式过程摘要] 证据：live smoke 首个事件为 thinking/stream_start。
• 在 api/v1/router.py 注册小财管家接口。[CONCEPT: 后端] 证据：运行中 /api/v1/steward/plans 返回 200。
• 保证所有输出到 ontology_fields 的业务字段只使用 canonical ontology fields。[CONCEPT: 本体字段约束] 证据：测试断言 occurred_date、transport_type、reason_value 不进入输出字段。
• 强化模型提示词和规则兜底，确保“未来出差/去某地几天/部署支撑”即使未出现“申请”也识别为费用申请。[CONCEPT: 任务识别与拆分] 证据：live smoke 将“明天出差北京3天...”拆为 expense_application,reimbursement。

阶段三：前端入口和弹窗

• 将首页输入区主文案调整为“小财管家”，提示语体现可处理多任务。[CONCEPT: 前端] 证据：PersonalWorkbench.vue 标题和 placeholder 已更新。
• 增加 steward 会话类型，首页复杂输入默认进入小财管家模式。[CONCEPT: 前端] 证据：SESSION_TYPE_STEWARD 与首页 sessionType 已接入。
• 小财管家模式下隐藏“智能体切换”工具条。[CONCEPT: 前端] 证据：shortcuts 在 isStewardSession 下返回空数组。
• 小财管家模式下标题显示“小财管家”，副标题说明“统一财务任务编排入口”。[CONCEPT: 前端] 证据：assistantHeaderTitle 和 assistantHeaderDescription 已按 steward 分支处理。
• 小财管家模式下不展示欢迎界面。[CONCEPT: 前端] 证据：useTravelReimbursementSessionState.js 对 steward 空会话返回空消息，并过滤旧欢迎消息快照。
• 小财管家模式下使用专属底部输入框，不展示日期选择、差旅计算器和业务时间标签。[CONCEPT: 前端] 证据：TravelReimbursementCreateView.vue 按 isStewardSession 渲染 steward-composer-row。
• 新增前端小财管家计划服务，调用 POST /steward/plans。[CONCEPT: 后端] 证据：web/src/services/steward.js 已新增 fetchStewardPlan。
• 新增小财管家视图模型，生成过程摘要、任务计划卡片和附件归集卡片。[CONCEPT: 流式过程摘要] 证据：stewardPlanModel.js 和 TravelReimbursementMessageItem.vue 已接入 stewardPlan。
• 支持后端 thinking 事件真流式呈现为折叠式意图识别气泡。[CONCEPT: 流式过程摘要] 证据：useStewardPlanFlow.js 通过 fetchStewardPlanStream 接收 thinking 事件，并用 typeStewardThinkingEvent 将每条过程摘要逐字输出到折叠气泡。
• 支持小财管家最终正文逐字流式输出，正文完成前不展示确认按钮。[CONCEPT: 流式过程摘要] 证据：useStewardPlanFlow.js 新增 typeStewardPlanText，计划完成后进入 typing 状态逐字追加正文，完成后再注入 suggestedActions。
• 意图识别过程放在系统回复气泡上方，作为不同颜色的独立折叠气泡，完成后默认折叠。[CONCEPT: 流式过程摘要] 证据：TravelReimbursementMessageItem.vue 将 steward-intent-bubble 放在 message-bubble 上方，steward-plan-block 只渲染任务和附件结果。
• 统一小财管家思考折叠气泡与正文气泡宽度，避免思考气泡长于正文框。[CONCEPT: 流式过程摘要] 证据：has-steward-plan 消息栈统一为 760px，思考气泡和正文气泡同宽。
• 优化小财管家最终正文和任务卡片层次，用户可见内容不直接展示本体字段名。[CONCEPT: 用户可见结果展示] 证据：stewardPlanModel.js 第一屏使用 Markdown 标题、段落和顺序列表说明“先做什么、后做什么、交给哪个助手做什么”，但不展示置信度和字段缺口；useStewardPlanFlow.js 将第一屏标记为 initialSummaryOnly，TravelReimbursementMessageItem.vue 不再渲染第一屏任务详情卡片；后续步骤如需展示待补充项，再按独立列表行展示业务名称和填写说明。

阶段四：确认与分派

• 为每个创建/绑定/提交类动作生成确认按钮，不确认不执行。[CONCEPT: 用户确认] 证据：接口返回 confirmation_count=4，前端转为 suggested actions。
• 将小财管家确认区改为“只展示当前下一步主动作”，存在申请任务时优先进入申请助手。[CONCEPT: 用户确认] 证据：buildStewardSuggestedActions 只返回下一步动作，优先 confirm_create_application。
• 支持用户输入“确定”触发小财管家的下一步动作，而不是重新生成计划。[CONCEPT: 用户确认] 证据：useStewardPlanFlow 会查找待确认的小财管家动作并执行。
• 支持小财管家隐藏委派申请/报销能力，执行后保留小财管家会话并继续引导剩余任务。[CONCEPT: 执行流] 证据：sessionTypeOverride 和 stewardContinuation 已接入前端提交流程。
• 支持小财管家确认后的隐式委派继续流式输出，正文完成后再展示申请核对表、报销核对卡片和确认按钮。[CONCEPT: 流式过程摘要] 证据：useTravelReimbursementSubmitComposer.js 新增 typeStewardDelegatedMessage，申请预览与 orchestrator 结果均先流式思考、再逐字正文、最后挂载结构化 payload；npm.cmd --prefix web run build 成功。
• 小财管家委派申请/报销能力期间不打开右侧单助手执行流程面板，用户可见身份保持“小财管家”。[CONCEPT: 流式过程摘要] 证据：stewardDelegated 分支跳过 flow step 与 review panel scope，并在最终消息设置 assistantName: '小财管家'；stewardPlanModel.js 助手标签兜底不再显示“财务助手”。
• 小财管家在后续步骤发现关键缺口时，主动转成可回答的问题和选项，而不是只展示待补充表格。[CONCEPT: 用户可见结果展示] 证据：useTravelReimbursementSubmitComposer.js 在申请核对缺少“出行方式”时只输出主动追问和火车/飞机/轮船选项，不提前挂载 applicationPreview；stewardPlanModel.js 的内部 carry_text 不再把“高铁、飞机”等示例写进缺字段提示，避免本地抽取误当成用户已选择；TravelReimbursementCreateView.js 在用户选择后不再直接补旧表格，而是重新进入小财管家的委派流；web/tests/expense-application-fast-preview.test.mjs 覆盖该回归。
• 用户补齐出行方式后，小财管家必须先思考、模拟查询票据和测算金额，再展示申请核对表。[CONCEPT: 用户可见结果展示] 证据：stewardFieldCompletionModel.js 将补齐字段后的当前任务、本体字段和旧预览重组为续跑输入；TravelReimbursementCreateView.js 的 continueStewardApplicationFieldCompletion 调用 submitComposerInternal 触发流式思考、申请复核和费用测算，不再调用 commitApplicationPreviewEditor 直接闪现表格。
• 防止残留预算上下文抢占小财管家的申请续跑链路。[CONCEPT: 执行流] 证据：budgetAssistantReportModel.js 不再因存在 initialBudgetContext 就无条件进入预算编制报告；useTravelReimbursementSubmitComposer.js 对 stewardDelegated 显式跳过预算编制分支；expense-application-fast-preview.test.mjs 覆盖“申请续跑 + 残留预算上下文”不得进入预算编制。
• 支持用户直接输入“确认/无误/可以提交”命中当前申请核对表提交动作，而不是重新规划。[CONCEPT: 用户确认] 证据：TravelReimbursementCreateView.js 通过 handleStewardRuntimeDecision 优先请求运行时决策智能体；模型返回 submit_current_application 后复用 confirmApplicationSubmit；本地 handleApplicationSubmitConfirmationText 仅作为模型不可用时的兜底；提交成功后标记 applicationSubmitConfirmed，避免后续重复提交；测试 text confirmation submits pending application preview before replanning steward task 覆盖该优先级。
• 增加小财管家运行时决策智能体，把“确认、继续下一项、补字段、重新规划”的上下文判断迁到后端 function calling。[CONCEPT: 用户确认] 证据：POST /steward/runtime-decisions 调用 StewardRuntimeDecisionAgent，通过 submit_steward_runtime_decision 返回 submit_current_application、continue_next_task、fill_current_slot、plan_new_tasks 等动作；前端 handleStewardRuntimeDecision 先提交 runtime_state，再执行模型返回的结构化动作，本地规则仅兜底。
• 增加第二层任务字段决策智能体，动态判断当前任务应追问用户还是展示核对结果。[CONCEPT: 算法与公式] 证据：POST /steward/slot-decisions 调用 StewardSlotDecisionAgent，通过 submit_steward_slot_decision function calling 输出 ask_user / render_preview、canonical 缺失字段、问题和选项；前端 useTravelReimbursementSubmitComposer.js 在小财管家委派申请时消费该决策。
• 防止字段决策模型把申请阶段非阻塞字段误判为用户必填项。[CONCEPT: 用户可见结果展示] 证据：StewardSlotDecisionAgent 过滤 amount、attachments、employee_no、department_name、employee_name，模型误返 ask_user 且过滤后无缺口时改为 render_preview；前端 APPLICATION_NON_BLOCKING_ONTOLOGY_FIELDS 同步过滤兜底缺口和选项；测试覆盖附件/员工编号误判。
• 小财管家思考气泡必须体现业务意图和关键缺口，不能退化为系统执行日志。[CONCEPT: 流式过程摘要] 证据：steward_planner.py 将差旅申请缺少“出行方式”纳入计划缺口并追加业务缺口思考事件；useTravelReimbursementSubmitComposer.js 和 TravelReimbursementCreateView.js 的确认后思考改为读取任务摘要、已识别信息和待补充项。
• 确认申请任务后，将任务摘要分派到现有申请助手会话。[CONCEPT: 执行流] 证据：确认动作携带 session_type=application 和 auto_submit=true。
• 确认报销任务后，将任务摘要和附件带入现有报销助手会话。[CONCEPT: 执行流] 证据：确认动作携带 session_type=expense、carry_files=true 和 auto_submit=true。
• 附件归集建议确认后，将选中附件作为报销助手上下文继续处理。[CONCEPT: 附件归集] 证据：附件归集确认动作携带归集附件名称和排除附件名称。

阶段五：测试与验证

• 新增 server/tests/test_steward_planner.py，覆盖多任务拆解、相对日期、附件归集、确认动作和流式事件。[CONCEPT: 测试方案] 证据：新增 4 个后端定向测试。
• 补充 function calling 定向测试，覆盖模型工具参数、canonical 字段清洗、附件归集和规则兜底。[CONCEPT: 后端单元测试] 证据：test_steward_planner.py 新增 fake function calling 路径，test_runtime_chat_service.py 新增 tools payload 用例。
• 后端测试在 Docker x-financial-main:/app 内执行，超时控制在 60s 内。[CONCEPT: 容器验证] 证据：pytest -q server/tests/test_steward_planner.py server/tests/test_runtime_chat_service.py 结果 13 passed。
• 新增或更新前端定向测试，覆盖小财管家标题、隐藏智能体切换和计划展示。[CONCEPT: 前端测试]
• 运行前端构建或定向测试，确认 UI 编译通过。[CONCEPT: 测试方案] 证据：npm.cmd run build 成功。
• 通过接口或页面可见结果证明用户最终看到小财管家计划和确认点。[CONCEPT: 指标与验收] 证据：容器接口返回 3 个任务、3 份归集附件、1 份排除附件和 4 个确认动作。