确定性评分定时任务构建器与 Agent 协作

[itsadrianxv]

确定性评分定时任务构建器规格

Problem Statement

当前确定性评分定时任务已经具备多周期行情、MACD、KDJ、复合条件、确定性评分、执行队列、结果表和 Excel 输出，但配置入口仍以 Agent 对话和评分规则 JSON 文本框为主。

这会带来三个直接问题：

• 投资者需要理解内部 JSON 结构，才能检查条件、分值、阈值和指标参数是否正确。
• Agent 生成的复杂规则即使通过结构校验，也可能在用户没有发现的情况下改变股票范围、调度或投递设置。
• 草稿校验、预览、版本发布和确定性执行没有形成一个统一的用户可见闭环，Agent 的等待时间也可能被错误地放到配置关键路径上。

核心投资者需要能够和 Agent 讨论意图，但最终必须由页面上的评分规则构建器核对和确认复杂配置。

Solution

建设一个以评分规则构建器为主页面的确定性评分定时任务配置流程。构建器使用“规则列表 + 条件组编辑器”表达评分逻辑；Agent 作为可折叠的异步辅助面板，返回结构化变更集并填入未生效草稿。用户可以逐条调整，但对整套任务一次确认。

所有草稿、预览、启用、版本和投递状态通过 Deterministic Controller 这一权威应用 seam 处理。页面和 Agent 都不能直接写入执行计划或触发外部副作用。Python 解析器、语义校验器和评分引擎继续作为确定性执行链路，预览与实际执行复用同一条链路。

预览只展示已确认的确定性结果字段：样本股票、总分、规则得分、叶子条件状态、数据截止时间以及缺失或滞后警告；不新增自然语言“语义字段”，也不以 Agent 解释替代评分结果。

User Stories

1. 作为核心投资者，我希望从定时任务页面直接创建确定性评分任务，以便不必先知道应当如何向 Agent 提问。
2. 作为核心投资者，我希望构建器是配置的主页面，以便关闭 Agent 后仍能完整完成任务。
3. 作为核心投资者，我希望在同一页面查看构建器和 Agent 辅助面板，以便讨论规则时不需要在聊天页和配置页之间来回切换。
4. 作为核心投资者，我希望在桌面端看到主构建器和可折叠 Agent 面板，在移动端能切换两者，以便不同屏幕都能完成配置。
5. 作为核心投资者，我希望使用单页连续编辑器并直接跳转到任务、调度、范围、规则、筛选、投递和预览分区，以便修改复杂配置时保持上下文。
6. 作为核心投资者，我希望看到规则列表，以便快速扫描规则名称、条件摘要、分值和当前变更状态。
7. 作为核心投资者，我希望复制一条当前规则并再修改它，以便快速构建相似条件。
8. 作为核心投资者，我希望从当前草稿移除一条规则，以便暂时不让它进入执行计划；未保存的移除可以撤销，保存后规则只保留在历史版本中。
9. 作为核心投资者，我希望每条规则内部使用“全部满足”“任一满足”和“取反”条件组，以便表达多周期和嵌套逻辑。
10. 作为核心投资者，我希望深层条件组能够进入聚焦视图编辑，以便 8 层以内的复杂规则不会因无限横向缩进而难以阅读。
11. 作为核心投资者，我希望构建器支持现有的 OHLCV、K 线方向、MACD 和 KDJ 指标，以便配置可以覆盖当前确定性执行能力。
12. 作为核心投资者，我希望 K 线方向提供阳线、阴线和十字星三个受控选项，以便不需要记忆内部字符串值。
13. 作为核心投资者，我希望在添加条件时自动生成所需的指标声明，以便不需要手工维护重复的指标数组。
14. 作为核心投资者，我希望在指标参数区域调整 MACD 和 KDJ 参数，以便集中检查参数而不是在每条规则中重复修改。
15. 作为核心投资者，我希望同一指标的冲突参数被明确提示，以便系统不会静默覆盖或合并我的设置。
16. 作为核心投资者，我希望原子条件使用周期、指标、操作符和值控件，以便页面主动排除非法输入。
17. 作为核心投资者，我希望 between 使用两个有序数字，交叉操作明确表示穿越数值阈值，以便理解执行语义。
18. 作为核心投资者，我希望指标类型和操作符不兼容时在保存前看到具体错误，以便不会等到定时执行才发现配置无效。
19. 作为核心投资者，我希望规则分值以非负数字表示，以便明确总分等于命中规则分值之和，而不是被系统隐式归一化。
20. 作为核心投资者，我希望页面显示最高可能得分和筛选阈值，以便判断阈值是否会导致无入选结果。
21. 作为核心投资者，我希望即使筛选阈值高于最高可能得分，也可以保存和启用任务，以便有意配置无入选结果时不会被系统阻断。
22. 作为核心投资者，我希望这种无入选配置显示明确警告，以便知道没有股票入选是配置结果而不是执行失败。
23. 作为核心投资者，我希望在“全部 A 股”和“指定股票”之间选择范围，以便明确评估集合。
24. 作为核心投资者，我希望通过代码或名称搜索、批量粘贴和去重来维护指定股票，以便快速配置大批股票。
25. 作为核心投资者，我希望格式错误能够定位到具体股票条目，以便快速修正而不必查看 JSON。
26. 作为核心投资者，我希望内部统一使用六位 A 股代码，页面和 Agent 能规范化后缀代码或名称，以便不把 TuShare 格式暴露到评分规则中。
27. 作为核心投资者，我希望选择前复权、后复权或不复权，并默认使用前复权，以便明确行情口径对指标的影响。
28. 作为核心投资者，我希望复权方式改变后当前预览失效，以便不会误用旧口径的评分结果。
29. 作为核心投资者，我希望使用每天、每周指定星期或每个交易日等调度预设，以便不需要填写 cron 表达式。
30. 作为核心投资者，我希望明确看到运行时间、时区、市场日历和可选起止时间，以便调度含义不会依赖隐式时区。
31. 作为核心投资者，我希望 Agent 只能把自然语言转换为页面支持的调度字段，以便不会产生隐藏的调度语义。
32. 作为核心投资者，我希望默认仅保存站内结果，以便创建任务不会意外产生外部发送副作用。
33. 作为核心投资者，我希望输入飞书官方 HTTPS Webhook URL 后即可配置飞书投递，不需要 OAuth 或额外权限设置。
34. 作为核心投资者，我希望 Webhook URL 被加密保存、脱敏展示且不进入 Agent 上下文和日志，以便发送凭证不会泄露。
35. 作为核心投资者，我希望飞书消息固定发送 Top N 入选摘要和站内结果或 Excel 链接，以便消息简洁且结果完整可查。
36. 作为核心投资者，我希望把 Top N 设置为 1-50 并配置空结果是否发送，以便控制消息容量；空结果默认发送。
37. 作为核心投资者，我希望 Agent 只能提出规则、范围、调度等结构化变更集，以便页面成为复杂配置的权威入口。
38. 作为核心投资者，我希望 Agent 变更集自动进入未生效草稿并明确标记新增和修改，以便不必逐条点击应用，同时能看出变化。
39. 作为核心投资者，我希望在 Agent 变更进入草稿后逐条编辑，最后整套确认一次，以便兼顾效率和精度。
40. 作为核心投资者，我希望草稿改变后只需选择“覆盖草稿”或“丢弃 Agent 变更”，以便不承担复杂的自动合并冲突处理。
41. 作为核心投资者，我希望 Agent 遇到影响评分或调度结果的歧义时先提出聚焦问题，以便模型不会替我猜测关键参数。
42. 作为核心投资者，我希望安全默认值被明确标记并出现在最终摘要中，以便知道哪些设置来自默认值。
43. 作为核心投资者，我希望任务版本只保存结构化配置而不保存 userPrompt，以便自然语言不会成为执行事实。
44. 作为核心投资者，我希望 Agent 会话可以单独回看和审计，但不进入任务版本，以便解释记录与执行配置分离。
45. 作为核心投资者，我希望本地编辑立即响应，服务端在约 800ms 防抖后自动保存，并显示保存状态，以便输入不会等待网络。
46. 作为核心投资者，我希望保留明确的“保存草稿”按钮，以便在关键节点主动保存。
47. 作为核心投资者，我希望规则草稿在应用和保存前都经过统一的服务端结构与语义校验，以便 Agent 和手工编辑使用同一标准。
48. 作为核心投资者，我希望校验错误定位到具体规则或条件组，以便快速修复复杂配置。
49. 作为核心投资者，我希望草稿可以先保存而不立即进入调度，以便分阶段完成复杂任务。
50. 作为核心投资者，我希望首次启用或规则发生实质变化时必须完成当前版本预览，以便启用前核对真实评分结果。
51. 作为核心投资者，我希望指定股票范围默认使用前 5 只作为预览样本，以便快速检查规则。
52. 作为核心投资者，我希望全部 A 股任务由我选择 1-20 只预览样本，以便不会隐式执行全市场预览。
53. 作为核心投资者，我希望预览复用真实解析器、数据适配器和评分引擎，以便预览不会与定时执行产生两套结果。
54. 作为核心投资者，我希望预览显示样本、总分、规则得分、叶子条件状态、数据截止时间及缺失或滞后警告，以便核对确定性输出；预览不增加自然语言语义字段。
55. 作为核心投资者，我希望预览异步运行且不会锁住构建器，以便取数期间仍可继续编辑。
56. 作为核心投资者，我希望所有样本都无法评估时不能启用，部分样本无法评估时可以带警告启用，以便区分数据失败和部分数据缺失。
57. 作为核心投资者，我希望数据滞后只产生警告但仍可保存、启用、执行和投递，以便市场数据延迟不会悄悄停止任务。
58. 作为核心投资者，我希望最终启用摘要一次展示调度、股票范围、指标参数、规则分值、阈值、预览样本、数据截止时间、警告和脱敏投递设置，以便不需要阅读 JSON。
59. 作为核心投资者，我希望首次创建先保存为草稿，只有我明确点击启用后才进入调度，以便 Agent 不能自动产生任务。
60. 作为核心投资者，我希望启用中的任务版本不可变，修改形成新草稿并从下一次调度生效，以便历史结果能追溯到当时规则。
61. 作为核心投资者，我希望正在执行的任务继续使用启动时绑定的旧版本，以便编辑不会改变运行中的评分。
62. 作为核心投资者，我希望暂停只阻止未来执行，不取消运行中的执行，也不补发暂停期间错过的周期，以便暂停行为可预测。
63. 作为核心投资者，我希望立即执行绑定当前已发布版本并默认不投递，以便验证生产配置时不误用草稿或发送消息。
64. 作为核心投资者，我希望立即执行需要单独确认外部投递，以便全量执行和外部副作用清晰分开。
65. 作为核心投资者，我希望评分执行成功与飞书投递状态分离，以便投递失败不会导致重复评分。
66. 作为核心投资者，我希望投递对网络错误、429 和 5xx 最多重试 5 次，配置错误直接失败，以便投递不会无限发送。
67. 作为核心投资者，我希望单次执行失败、数据滞后或投递失败不会自动暂停任务，以便偶发故障不会让长期任务悄悄停止。
68. 作为核心投资者，我希望任务列表显示状态、下一次运行、最近执行、数据截止时间、入选数量和最近投递状态，以便快速判断任务是否正常。

Implementation Decisions

• 以 Deterministic Controller 作为唯一权威应用 seam。它接收结构化草稿和结构化 Agent 变更集，负责规范化、草稿保存、统一校验、预览请求、版本发布、启用、暂停、立即执行和投递状态结算。
• Agent Runner 只负责在受限执行边界内讨论、解释并生成候选变更集；它不能写权威状态、读取或替换 Webhook 凭证、选择隐藏数据源、自动启用或直接调用外部发送适配器。
• 评分规则构建器是主页面，Agent 是可折叠辅助面板；桌面端并列显示，移动端可切换。构建器采用单页连续编辑器，不以多步骤锁定配置。
• 评分规则列表使用当前草稿中的规则作为唯一编辑集合。规则移除后不保留停用态，不进入当前草稿或执行计划；未保存移除可以撤销，保存后只在不可变历史版本中保留，不搭建从历史复制为新规则的专门入口。
• 条件组支持 all、any、not，条件树最多 8 层、200 个节点；超过约 3 层时使用进入条件组的聚焦编辑视图。规则最多 50 条，指标声明最多 20 个。
• MVP 只允许已登记指标和操作符。指标目录包含 OHLCV、candle.direction、MACD 和 KDJ；K 线方向值为阳线、阴线和十字星。MVP 不支持任意自定义公式。
• 指标声明由条件选择驱动生成；同一指标集中显示参数，冲突参数必须显式解决。MACD 和 KDJ 参数沿用既有确定性 schema 的范围与默认值。
• 服务端维护指标类型、操作符和值类型的兼容目录。静态不兼容条件在保存前阻断；运行时真实缺少数据才产生 NOT_EVALUATED。
• 每条规则使用非负规则分值，命中后计入总分；总分不归一化。minScore 高于最高可能得分仍允许保存和启用，但显示“不会产生入选结果”警告。
• 股票范围只提供“全部 A 股”和“指定股票”。领域值统一为六位 A 股代码；页面和 Agent 可接受名称或带交易所后缀的输入，进入领域边界时规范化，外部适配器再补充供应商代码格式。
• 调度只提供每日、每周指定星期和每个交易日预设，配置时间、时区、市场日历和可选起止时间；不提供 cron 输入。默认时区为 Asia/Shanghai，但页面必须显式显示。
• 用户不配置 provider 或 capability。执行计划所需的数据需求从结构化条件和指标参数派生，内部适配器负责选择确定性数据源。
• 复权方式提供前复权、后复权和不复权，前复权为默认值。复权方式变化会使预览失效。
• 投递默认 SAVE_ONLY。飞书投递由用户直接提供符合官方格式的 HTTPS Webhook URL，不需要 OAuth；URL 作为发送凭证加密保存、脱敏展示，不进入 Agent 上下文、日志或错误消息。只允许飞书官方 Webhook 格式，不允许任意域名请求。
• 飞书消息固定发送 Top N 入选摘要和站内结果或 Excel 链接，N 范围为 1-50，空结果发送可配置且默认开启。飞书投递最多重试 5 次；评分执行结果与投递状态分离。
• 任务版本只保存结构化执行配置，不保存 userPrompt。Agent 会话由 Agent Runtime 独立保存，不作为任务版本输入。
• Agent 变更集必须带有生成时的草稿版本信息。当前草稿变化时不做自动合并，用户只能选择覆盖当前草稿或丢弃 Agent 变更。
• 草稿采用本地即时更新、约 800ms 防抖服务端自动保存和显式保存按钮。自动保存失败不阻塞编辑；最终启用前必须成功保存并通过校验。
• 所有 Agent 候选和手工草稿在应用、保存和启用前走同一个服务端结构与语义校验入口；系统不得静默改写用户的条件、分值、阈值、范围或投递目标。
• 首次启用和规则发生实质变化必须进行当前版本的只读评分预览。指定股票范围默认使用前 5 只；全部 A 股必须由用户选择 1-20 只样本。预览异步执行，不产生外部投递，不锁住构建器。
• 预览必须复用真实解析器、数据适配器和评分引擎，返回样本、总分、规则得分、叶子条件状态、数据截止时间和缺失/滞后警告，不包含额外自然语言语义字段。全样本无法评估阻止启用，部分样本无法评估允许带警告启用；数据滞后不阻止保存、启用、执行或投递。
• 立即执行使用当前已发布版本的完整股票范围，默认不投递；外部投递必须单独确认。草稿不能被立即执行直接使用。
• 启用版本不可变；修改生成新草稿，发布后从下一次调度生效；运行中的执行绑定旧版本。暂停只阻止未来执行，不补发错过周期。
• 任务列表显示状态、调度摘要、下一次运行、最近执行状态、数据截止时间、入选数量和投递状态；复杂规则只在详情页展开。
• 本规格不要求新增自定义公式语言、任意 cron、Agent-only JSON 确认、任意 Webhook、飞书 OAuth、多渠道矩阵、历史版本复制入口或浏览器验证。
• 交互性能目标为：本地编辑和结构反馈不超过 100ms；语义校验在防抖后 P95 ≤ 800ms；保存/创建任务 P95 ≤ 1.5s；Agent 首次有意义反馈 P95 ≤ 5s；可应用规则草稿 P95 ≤ 20s；Agent 硬超时 45s。Agent 不在构建器关键路径上。

Testing Decisions

• 测试只验证外部行为和模块契约，不验证 React 内部状态变量、具体组件层级或实现细节。测试名称和断言使用评分规则构建器、确定性评分、草稿、预览、任务版本和飞书 Webhook 投递等领域词汇。
• 以 Deterministic Controller 应用契约作为最高测试 seam，覆盖草稿规范化、自动保存、版本冲突、统一校验、预览失效、启用、暂停、立即执行和投递状态分离。
• 延伸现有定时任务设置路由、工具和页面测试，验证页面发起结构化操作后得到的草稿、校验错误、变更标记、确认摘要和状态，而不是验证 JSON textarea 或组件实现。
• 延伸现有 Python 确定性评分测试，覆盖指标目录、操作符和值类型兼容、条件树深度/节点上限、三态条件、MACD/KDJ 参数、规则分值、阈值高于最高分、排名和完整规则明细。
• 新增 Web 与 Python 之间的执行计划契约测试，确认六位代码、指标声明、条件树、复权方式和规则分值在校验、预览与真实执行之间保持一致。
• 新增 Agent 变更集契约测试，覆盖新增规则、修改条件、移除规则、范围与调度填充、冲突时覆盖/丢弃、非法变更拒绝、不能读取或替换 Webhook，以及 Agent 超时后构建器仍可保存。
• 新增预览应用契约测试，覆盖指定范围默认 5 只、全部 A 股强制 1-20 只样本、全样本不可评估阻断、部分不可评估警告、零命中合法、数据滞后继续启用和预览不投递。
• 新增任务版本与调度测试，覆盖启用版本不可变、下一周期生效、运行中使用旧版本、暂停不补发、立即执行只使用已发布版本和单次失败不自动暂停。
• 新增 Webhook 安全和投递契约测试，覆盖官方 HTTPS 格式、任意域名拒绝、加密/脱敏边界、Agent/日志不泄露、Top N、空结果、配置错误分类、网络/429/5xx 最多 5 次重试和评分成功与投递失败分离。
• 新增草稿性能测试，使用稳定的测试数据和固定请求样本测量本地反馈、语义校验、保存、Agent 首反馈和可应用草稿的 P95；Agent 性能测试不能阻断确定性配置测试。
• 数据库生命周期和投递并发测试沿用现有 PostgreSQL contract test 先例；Redis 只验证至少一次唤醒，数据库仍是任务生命周期和版本的权威状态源。
• 遵守项目约束：Web 测试放在 web/tests，中文文件使用 UTF-8，不进行浏览器验证。

Out of Scope

• 任意自定义公式、脚本、用户定义函数或新的公式语言。
• 任意 cron 表达式、隐藏调度字段或 Agent 自行决定的运行时机。
• 除现有 OHLCV、K 线方向、MACD、KDJ 外的新指标和新数据供应商选择界面。
• 飞书 OAuth、账号权限管理、多渠道投递矩阵和任意域名 Webhook。
• Agent 直接写权威状态、直接发送外部消息、自动启用任务或只让用户确认 Agent JSON。
• 预览中的自然语言语义字段、用 Agent 解释替代确定性评分结果、前端自行模拟评分。
• 从历史版本复制规则的专门入口；只保留历史查看能力和未保存草稿移除的撤销。
• 因数据滞后自动阻止任务、因单次失败自动暂停任务或补发暂停期间的执行。
• 研究事件、个性化研究雷达、定时简报和其他非确定性后台研究工作流的改造。
• 浏览器端验收、部署、真实用户数据迁移和运行时整体数据权利/合规资格判定。

Further Notes

• 现有确定性评分执行核心、队列、结果表、Excel 输出和部分测试可以复用；主要缺口在配置应用层和用户界面，而不是重新实现评分引擎。
• 当前实现中的 JSON 预览、必填 userPrompt、用户可见数据源字段、静态 targetRef 投递目标以及未统一覆盖所有草稿路径的语义校验，都需要按本规格收敛。
• 规格不改变已经确认的 Agentic Workflow 边界：Agent 生成候选，确定性控制验证并接管权威状态和外部副作用。
• 本规格完成后应拆分实施任务，但拆分任务不得重新引入 Agent-only 规则确认、静默规则修正或无法追溯的版本变更。