Imported from zwluestc/AgenQA-world-skill (
refined_context/agents_discussion_mcp_scicode/refs/AGENTS.md). Install upstream withnpx skills add zwluestc/AgenQA-world-skill --skill refs. Copyright stays with the author.
For Codex/Cursor/Claude
我可能会在你工作的时候,同时进行一些其他修改,请你不要直接删除这些修改。
机器环境 参考 /mnt/innovator/code/fengLang/BrightPedia/AGENTS.md
本 Repo 说明
架构重要参考
文档与代码的一致性约定
- 本仓库中,代码实现代表最新意图;文档(含
docs/下的说明)可能过期,仅作参考。 - 当文档描述与代码行为不一致时:
- 以当前代码逻辑为准;
- 可以更新/修正文档,使其贴合代码;
- 不要仅依据文档去修改代码逻辑,除非用户在对话中明确要求按文档重构或恢复某种行为。
- 在补充设计说明或写新文档时,应优先从现有代码抽象出行为,再进行总结,而不是反向用文档假定行为。
文档目录说明
docs/problems/:记录在实现gen_problems_agent.md过程中遇到的问题、发现和思考。用于梳理题目生成质量、LLM 行为模式等观察,以及需要进一步研究的方向。详见docs/problems/README.md。
Prompt 系统架构
代码真源原则
Prompt 系统中的说明文本遵循"代码真源"原则:
-
Domain 层定义:所有结构说明、字段定义、metrics 说明等都在
sciclone/domain/下定义,作为单一真相源。known_tree.py:KNOWN_TREE_DESCRIPTION- Known 树结构说明solver_schema.py:solver_output_schema_text()- Solver 输出字段说明metrics_schema.py:METRICS_AND_SOLVERS_DESCRIPTION_ZH/EN+NOW_QA_VS_NOW_HEADTAIL_DESCRIPTION_ZH/EN- Metrics/Solver 信号与 Now QA 概念说明- 其他
*_schema.py:各角色的输出字段说明
-
Prompt 片段聚合层:
Prompts/py_style/common.py作为可复用 prompt 片段的聚合层。- 从 domain 层导入说明文本(如
COMMON_KNOWN_TREE引用KNOWN_TREE_DESCRIPTION) - 定义通用的格式规范(如
COMMON_ANSWER_SCHEMA、COMMON_QUESTION_TYPES) - 各角色 prompt 通过
from .common import ...按需引用
- 从 domain 层导入说明文本(如
-
说明块索引:
sciclone/domain/spec_index.py提供代码化的说明块索引。- 列出所有说明块及其来源、使用位置
- 用于导航、文档化和工具化(如验证引用关系)
- 注意:索引只包含元数据,不包含实际 prompt 文本
文件组织
- 角色 Prompt:
Prompts/py_style/*.py- 各角色的 prompt 定义(director, draft, format, solver 等) - 通用片段:
Prompts/py_style/common.py- 可复用的 prompt 片段 - 代码真源:
sciclone/domain/*_schema.py- 字段定义和说明文本 - 索引:
sciclone/domain/spec_index.py- 说明块索引(元数据)
Prompt 风格与哲学
- 角色 Prompt 的首要职责是管理好上下文与 IO 结构:清晰暴露输入字段、输出 schema 与目标角色(target),而不是把“分析过程”写死在 checklist 里。
- 对于 Diagnose / Revise 这类分析型角色:
- 用简洁的任务描述 + 关键上下文(Known/Background/GT Answer/Solver Feedback/Solver Answers/Director Notes),让 LLM 自主组织推理路径;
- 避免堆叠细粒度的操作清单(逐条问答式 checklist),除非是结构/协议层面的硬约束(例如:输出字段名、JSON/Tagged 协议等)。
- 新增提示时,优先以“目标导向 + 约束边界”的方式引导(例如:保证逻辑自洽、不要重出新题、不要覆盖 GT 含义),而不是对中间推理步骤进行强制枚举。
- 若确实需要强调某些关注点(如利用 solver_feedback、检查 well-posed),应作为示例性提醒而非穷尽式规范,让不同模型有空间发挥各自的分析风格。
关于"泛化的约束要求"(全局原则)
- 避免机械化/程序化约束:对“反平庸/多样性/方法脚印/新颖性/严谨性”等泛化目标,避免用硬编码的数量阈值或启发式(如“中间量≥N”“操作类型≥M”“标签≥K”)作为必过条件或默认过滤标准。
- 原则优先:以第一性原理和终极目标在 Prompt 中引导(例:可复现、多步推理、信息充分但不冗余、逻辑自洽),而非以具体计数替代目标本身。
- 自检边界:允许结构/一致性层面的自检(JSON 结构、Step 递增、head–tail 可复现、单位/口径一致、唯一可机判答案等);避免依赖主观或容易失真的数量化指标作为强约束。
- 配置约束:若确需引入这类启发式指标,只能作为“诊断/观测”用途,并置于显式开关之后,默认关闭,且不得作为通过/失败的硬门槛。
以上适用于本仓库所有模块(Prompt、实现、评测、文档)。
系统设计原则
Fail-Fast 原则
- 核心组件(Director/Draft/Format 等)失败应立即暴露,避免用 fallback 掩盖问题。
- 重试仅用于短暂抖动;多次失败后抛出异常并终止 episode。
- 避免用 fallback 让后续开发者误以为“失败是正常的”;如必须对“可选能力”降级,应显式记录(error 日志/指标)。
Pipeline 职责边界(与 Fail-Fast 的关系)
- Pipeline 已通过一系列 roles(Diagnose/Revise/Format/…)设计了“发现问题→修复/兜底→继续推进”的闭环; 代码层不应自作主张插入“隐式兜底/隐式修复”来篡改角色职责,也不应以硬校验随意中断链路。
- 对于 role 输出的“协议/契约偏差”(例如字段缺失、轻微格式错误、引用不一致等):
- 代码应记录与上报(error/warn 日志 + 指标/结构化产物),把问题可观测化;
- 让 pipeline 的后续 roles 或显式的 Revise 路径承担修复职责;
- 仅允许不改变语义的确定性规范化(如去除不可见空白/换行导致的 ID 断裂),且必须显式记录。
Prompt 优先于 Pipeline 修复
- 模型行为问题优先改 Prompt;结构性问题再改 Pipeline(路由/状态/Graph)。
- 发现问题先判因(Prompt 质量 vs Pipeline 设计),避免用断路器/特殊逻辑等 Pipeline 复杂度掩盖 Prompt 缺陷。
代码真源与单一真相源
- 约束/字段说明只定义一处,通过引用复用,避免复制导致不同步。
- 共享约束集中在
Prompts/py_style/common.py(如COMMON_REUSED_REFS_RULES),不同模式通过引用保持一致。
问题可见性优于静默处理
- 用异常 +
error让问题可见、可监控、可诊断;避免warning+ 默认值/回退掩盖真实失败。
关于 Prompt 缩进/空白
- Pipeline 行为不依赖缩进/空白;缩进差异只影响 vendored
.prompt文件的字节级比对与可读性。 - 若逻辑文本已对齐,可暂时忽略纯缩进/空白问题;只有在需要让 vendored 文件与运行时输出完全一致时(便于检测漂移)才做对齐并重新运行
scripts/vendor_py_style_prompts.py。 - 避免在无功能变化时反复调整缩进,优先处理实际约束/泄露等行为问题。
开发环境与使用场景
-
Innovator 服务器(主要开发环境)
- 用途:代码开发、文档维护、常规运行与调试(含 GPU)。
- 依赖安装:
bash scripts/install_agents_deps_eval_scicode.sh(或按 README 手动安装)。 - 推理服务:优先通过
LLM_SERVICES_JSON指向私有端点的services.json,在配置里使用service_id解析。 - 网络范围说明:此前提到的
/mnt/innovator/code/fengLang/LLM/Infra/llm_service/configs等“内网/私有端点”均指 Innovator 集群的内网资源,不是阿里企业内网。 - 说明:
infra/service_client会清理代理相关环境变量以避免推理连通性问题;必要时设置NO_PROXY=127.0.0.1,localhost,::1。
-
阿里 Mac 电脑(主要用于内网 API)
- 用途:使用阿里内网的 OpenAI 兼容 API(Idealab/百炼 等)进行连通与实际调用测试。
- 快速使用:
- 导出密钥:
export IDEALAB_API_KEY="sk-..."(不要把 Key 写入代码库)。 - 运行示例配置:
python cli.py -c config/agent_idealab.yaml agent-run --max-steps 3 --output data/agent_run。
- 导出密钥:
-
连通测试脚本:
infra/llm_api/test_openai_compat_api.py(统一入口,支持/models、/chat/completions、/responses,并支持 stream 与多来源--source)。- 模型映射建议(可按需调整):
- instruct(director/operators):
qwen3-max - medium(solvers.medium):
gemini-2.5-pro-06-17或gpt-5-0807-global - strong(solvers.strong):
claude_sonnet4_5
- instruct(director/operators):
- 安全:统一用环境变量占位(例如配置里
${IDEALAB_API_KEY}),避免在仓库中保存任何明文密钥。 - 网络范围说明:阿里企业内网(Idealab/百炼)与 Innovator 集群内网完全不同;在 Mac 侧不要指向 Innovator 的
services.json,而应直接使用 Idealab 的兼容端点与 API Key。 - 域名标识:阿里企业内网常见域名带
alibaba-inc.com(如 Idealab:https://idealab.alibaba-inc.com/api/openai/v1)。 - 状态:百炼(DashScope
https://dashscope.aliyuncs.com/compatible-mode/v1)当前未在本仓库环境中验证;如需使用请自行在 Mac 环境测试并提供可用模型名。
- 模型映射建议(可按需调整):
大文件与额外存储(重要约定)
- 以后涉及 大文件/大体积产物(例如:数据集缓存、评测产物、zip/tgz 打包、长日志、模型输出大 dump 等),优先放到:
/data2/root/fenglang_data2 - 仓库内只保留必要的索引/README/小体积示例;避免把大文件直接写入 repo 工作区(也避免误提交)。
Git Style 规范
- 优先保证提交可回滚、可定位、可解释:一次提交聚焦一个目的(一个 bug/一个特性/一次重构)。
- 不要把无关改动混进功能提交(例如大范围的纯格式化、顺手改名、无关文件整理);如确需做,单独提交。
- 合并前优先用 rebase 保持线性历史;避免在功能分支里反复 merge 主干制造噪音。
- 不要提交明文密钥/Token/私有端点;配置用环境变量占位(例如
${IDEALAB_API_KEY})。 - 生成物/大文件按仓库既有惯例处理(例如
data/、logs/、vendored prompts);不确定时先问。
Git Commit Style 规范
Commit message 格式
推荐使用 Conventional Commits(允许 scope 为空):
<type>(<scope>): <subject>
type:feat/fix/refactor/docs/test/chore/ci/build/perf/revertscope:建议填模块/目录/组件名(例如sciclone、Prompts、infra),便于检索subject:一句话说明“做了什么”,避免写实现细节清单;中英文均可,但同一分支内尽量保持一致
Body / Footer(可选但推荐)
- Body:说明“为什么改 / 行为怎么变 / 怎么验证”,必要时补关键边界条件与影响面
- Footer:关联 Issue/任务(例如
Refs: #123/Closes: #123),破坏性变更用BREAKING CHANGE: ...
示例
fix(sciclone): handle empty solver_feedbackfeat(Prompts): add revise prompt for metrics mismatchdocs: update agent run notes
