Imported from WHUZhaoDingyi/research-compass-course-submission (AGENTS.md). Install upstream with npx skills add WHUZhaoDingyi/research-compass-course-submission. Copyright stays with the author.

AGENTS.md

本文件约束所有继续开发或运行 Research Compass 的 Agent。项目采用 V2 简洁知识助手架构；Framework Ready 只说明软件框架可运行，不代表课程的数据、天数和演示要求已经满足。

真实范围

• 唯一科研检索与知识写回范围是 20世界具身多模态模型/；固定系统记忆除外。
• 不读取、整理或迁移其他 Vault 笔记目录，不把旧 Agent/、MultimodalAgent/、测试 fixture、temporary demo、模板或 Agent 日志当作科研底座。
• 新材料、Idea、疑问和普通思考直接 Capture 到当前主题目录；V2 只有在严格条件满足时才向其 想法/ 子目录创建最多一篇派生 Idea。
• 当前真实笔记数、人工确认数和有效天数不得写死在文档中；分别以本次 index、evidence 和人工核对结果为准。
• 不从用户未明确表达的内容推断研究经历、能力、资源、正式方向或偏好。不确定项保留为待验证。

三个用户入口

用户日常只需理解：

1. capture：记录 source、idea、question 或 note，保留原始输入与来源；
2. process --preview → apply：把一篇新笔记连接到旧知识；
3. ask：以 RAG 方式从 Vault 检索并引用原文回答问题。

doctor、index、evidence、migrate 和 demo 是支持/维护命令。99_Agent/Decisions、Runs、Evidence、State 和 Migrations 是审批或审计目录，不是主要阅读入口。

用户主要阅读：

• 原始笔记中的 AGENT:CONNECTIONS 区域；
• 20世界具身多模态模型/90_Maps/Research-Map.md；
• 99_Agent/Answers/ 中的结构化问答结果。

V2 知识更新规则

• 默认以整篇源笔记生成一个 note_update；segment 仅用于来源归属和内部审计，不能再机械地一段生成一篇文件。
• 每次处理默认创建 0 篇派生笔记，最多 1 篇。
• 只有明确属于用户本人、置信度较高、独立可行动且与现有 canonical/title 不重复的 Idea，才可创建语义标题派生笔记。
• 基础资料、论文摘录和外部观点默认通过源笔记 Connections 与旧笔记建立关系，不再各自生成数字后缀文件。
• 相同观点优先链接已有笔记；不得仅因文件名冲突生成 -2/-3，也不得把“未检索到相似笔记”表述成创新。
• 所有派生内容必须标记 agent_generated: true、human_verified: false、source_note 和 agent_run。

Connections 与 Research Map

• Apply 在源笔记中维护唯一一对：

  <!-- AGENT:CONNECTIONS:START -->
  <!-- AGENT:CONNECTIONS:END -->

• Connections 必须直接显示：新增知识、相关旧笔记、关系类型、具体理由、双方原文证据、可信度、未解决问题和下一步。

• 关系只能引用本次检索白名单内的路径；模型提供的 source/target quote 必须通过本地原文校验。

• 使用包含完整相对路径的 Obsidian Wikilink，使 Backlinks 和 Graph View 形成真实文件关系。

• Research Map 的人工区域不改；AGENT:RECENT 区域每次由当前知识状态确定性替换，不继续追加 run 文件列表。

• Research Map 至少包含核心问题、主题入口、最近新增、新旧观点关系、Mermaid 关键关系图、冲突/待验证和下一步。

• 机器状态只写入 99_Agent/State/knowledge-graph.json，不得要求用户手工维护。

• Daily 只记录本次新增判断、关键连接、下一步和可选 Idea，不复制技术 trace。

索引与检索

• 索引只使用清洗后的用户/来源正文：去除通用 frontmatter 文本、旧 Agent 整理结果、AGENT:RUN 和 AGENT:CONNECTIONS 内容。
• 长笔记按 Markdown 标题切 chunk；超长小节再窗口化，不能只检索笔记开头。
• 保存并使用 human_verified、agent_generated/agent_run、source_type、source_note 和 family 信息。
• human_verified: true 的真实笔记作为优先证据；未核验内容标低可信。
• 未经人工确认的 Agent 派生内容不能作为主要事实依据，最多作为导航线索。
• 同一 source family 在一组结果中去重，并对高度相似结果做多样化。
• 检索结果必须保留路径、小节、连续原文片段、匹配原因、trust 和 family。

RAG Ask

• ask 只能基于本次 supplied evidence 回答；Research Profile/Vision 可帮助理解问题，但不能冒充外部事实证据。
• 每个实质判断必须引用已分配的 evidence_id，quote 必须是对应 evidence 的连续原文子串。
• Answer 清楚显示直接回答、证据表、笔记关系、不确定性和继续阅读。
• 后端不得自行编造路径、Wikilink、引用或通用背景；无检索证据时不调用模型补答案。
• 用户可读 Answer 与完整技术 trace 分开保存；两者都不得包含密钥。

Preview、Apply 与写回安全

• 文档和支持命令统一使用 python -m research_compass。
• process 只允许 Preview；真实写回必须使用独立 apply --run <run_id>。
• Preview 可创建 Decision/Run 审计文件，但不能修改来源、Research Map、Daily 或创建派生知识。
• Apply 前验证 source hash、plan/report hash、计划结构、Vault 边界、目标 hash、路径穿越、冲突和是否已经执行。
• 原始内容不得删除或改写；Connections 只能 upsert/replace 唯一受管区域。
• Research Vision 只可修改 AGENT:CANDIDATES 区域；Research Map 只可修改 AGENT:RECENT 区域。
• Apply 必须让源笔记、知识状态、Research Map、Daily 和审计产物在同一事务中保持一致。
• 默认不初始化 Git、不提交；只有显式 bootstrap --init-git 或 apply --commit 才执行。

来源与证据边界

• Capture 必须保留用户输入和来源 URL；同名文件使用可预测后缀，禁止覆盖。
• Capture 默认 human_verified: false；只有用户核对后才能手工改为 true，Agent 不得自行提升。
• 外部作者观点、论文声称、用户想法、Agent 推断、基础事实和未验证问题必须保持来源区分。
• 二手网页或博客不能获得与原论文/官方材料相同的证据强度。
• “本地没有相似笔记”不等于“学术上没有相关工作”或“想法创新”。

V1 兼容迁移

• migrate --preview 只在 99_Agent/Migrations/ 生成审查报告和 JSON，不修改核心笔记。
• 默认 migrate --apply --run <migration_id> 只是确认零改动兼容策略；旧文件继续保留。
• 迁移不得自动移动、删除、重命名、合并或批量改写数字命名派生笔记。
• V2 通过索引策略排除未核验 Agent 派生证据，并在未来 Apply 时重建 Map；人工是否归档/合并旧文件是独立决定。
• 遇到 malformed/nested/mismatched AGENT:RUN marker 必须停止迁移预览。

两阶段边界

阶段一负责软件能力：Vault 适配、Capture、索引/检索、后端、Preview/Apply、Connections、Research Map、Ask、Daily、日志、证据、迁移、测试和文档。

阶段二必须来自用户真实使用：

• 加入不少于 20 篇有真实内容并经过合理人工核对的科研笔记；
• 连续至少 5 天运行并保留真实时间线；
• 使用此前未预置的新笔记现场演示；
• 保存所有 AI 工具的完整原始对话、模型名称、版本和时间。

不得把 Framework Ready 表述为 Data Ready，也不得用 synthetic 数据、模板、Agent 派生文件或日志抬高真实笔记数量与有效天数。

测试约定

• 测试只能写 pytest 临时目录、明确 synthetic fixture 或 temporary Vault。
• 不用真实核心笔记做破坏性测试，不让测试依赖在线模型。
• MockBackend 仅用于测试；Heuristic 输出必须标规则推断和低置信度。
• demo --temporary 不计入真实笔记数、有效使用天数或现场演示。
• 修改后运行与风险相称的测试，只报告本次实际结果；不得沿用历史 91 passed 等旧数字。
• V2 至少覆盖：内容清洗、长笔记 chunk、可信度加权、family 去重、来源归属、quote/path grounding、最多一篇派生 Idea、Connections/Map、Ask 引用、Preview 不改核心笔记、Apply 幂等和迁移零改动。

Git 与证据

• 禁止 git reset --hard、git clean、伪造日期、修改 commit 时间或回填日志。
• 保留用户已有修改，不执行笼统 git add .。
• 显式 commit 时只暂存该 run 改动并记录真实 SHA。
• evidence 只汇总非 synthetic 的真实 Apply、对应 Daily 和 Git 历史；当前天数以实时报告为准。
• AI 原始对话必须另存完整内容；摘要、Decision 或 usage report 不能替代。

完成工作的报告方式

报告必须区分：

1. 实际创建或修改的文件；
2. 实际执行的测试及结果；
3. 是否真实调用 DeepSeekBackend 或 CodexBackend；
4. 当前纳入与人工确认的真实科研笔记数量；
5. 20 篇、5 天、现场演示和 AI 对话留档是否真实满足；
6. 用户日常在源笔记、Research Map 和 Answer 中能直接看到什么；
7. 下一次用户应执行的完整命令。