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
