MOS/mos_v3/mos_core/AGENTS.md

AGENTS.md

本文件是 MOS v3 的长期规则入口。它服务于跨会话、长任务、多轮调试和历史资料检索。

短常驻入口是 mos_always_rules.md。中文架构和流程总入口是 ARCHITECTURE_AND_FLOW.md。支持 always-on 规则的 agent 软件应优先安装或引用短规则文件；完整规则按触发条件回读。

1. 最高优先级原则

1. 一任务一线程，避免把所有项目历史混进同一会话。
2. 新会话不要全文加载历史，先用 make_bootstrap.py 生成启动包。
3. 重要结论必须写成 memory_card，不能只留在聊天里。
4. 关键结论必须带证据等级和回源入口。
5. 原始文件和 MOS Markdown 是事实源，SQLite/search 索引只是导航。
6. 压缩前必须写回：压缩前状态、当前目标、已完成内容、上下文摘要、已记忆内容、已确认事实、失败路径、有效路径、下一步最小动作。
7. 压缩、暂停、任务切换或新会话恢复时，必须遵守 memory_cards/context_compression_recovery_policy.md。
8. 凭据、密码、token、key 不写入记忆、不进入索引、不在输出中展示。
9. 默认不依赖常驻远端 server；读、写、修改、检索、索引、审核优先走本地一次性 CLI。
10. 在 Git 仓库内进行任何文件新增、修改、删除、生成、移动前，必须先做版本管理预检：查看 git status --short --branch，确认当前分支、远程和已有改动；MOS v3 仓库优先运行 tools/mos_cli.py git-preflight --repo <repo>。
11. 涉及 Git 提交、tag、release、push、merge、rebase、reset、clean 等操作时，必须先读取并遵守 memory_cards/agent_git_collaboration_policy.md。
12. 需要联想历史经验、相似失败、相关规则或跨会话记忆时，先执行 memory_association_policy.md，默认使用低负载稀疏联想；小模型只允许按需调用。
13. 可能依赖长期记忆的任务必须遵守 memory_log_plan_protocol.md：行动前 PLAN，行动后 LOG。
14. 写入长期记忆前必须遵守 memory_upsert_policy.md：先检索已有记忆，优先更新，避免重复新增。
15. 后续优化项、TODO、已完成但未关闭的 memory 必须遵守 memory_lifecycle_policy.md：区分长期知识、任务状态和动态动作项，必要时关闭、替代或归档。
16. memory card 应尽量写明 memory_type、namespace、source_of_truth、refresh_policy，避免作用域串台和双事实源。
17. 记忆重复、噪声变高或 task log 过长时，遵守 memory_consolidation_policy.md 做合并、提炼、去重和归档。
18. 多会话、多 agent 或 Git-backed memory 出现冲突时，遵守 memory_conflict_policy.md，先 diff、回源、再合并。
19. 记忆读写、检索、回源、写入和索引重建应按 memory_operation_trace_policy.md 记录可审计 trace。
20. 定期按 memory_scaffold_evaluation_policy.md 评估空搜索、重复写入、写前检索率和回源验证率。
21. MOS v3 采用 Skill + Memory + Tools + Eval 四层架构：先选 skill，再查 memory，用 tools 执行，用 eval 检查质量。

2. 信息分层

2.1 运行层

文件：

• active_task.md
• task_log.md
• session_bootstrap.md

用途：快速恢复当前任务。

2.2 结论层

文件：

• memory_cards/*.md

用途：保存高价值、可复用、可检索的结论。每条结论必须包含状态、标签、证据、回源入口和触发条件。

规则：

• 当前任务进度和临时待办不写入结论层。
• 需要长期跟踪的后续优化项必须写成结构化 action_items。
• 已完成、已替代或已归档的动作项必须更新状态和证据。
• 长期卡片应标注 memory_type、namespace、source_of_truth 和 refresh_policy。

2.3 原始证据层

文件：

• 历史日志
• 原始会话记录
• 代码仓库
• 远端路径
• 工具输出
• 文档资料

用途：回源验证，不默认常驻上下文。

2.4 派生索引层

文件：

• index/memory.sqlite3
• index/chunks.jsonl
• index/manifest.json

用途：检索导航。索引不是事实源，损坏或过期时必须从 Markdown 和原始资料重建。

2.5 Skill 层

文件：

• skills/skill_registry.json
• skills/*/SKILL.md

用途：保存可复用过程、触发条件、需要读取的 memory、使用工具和输出要求。Skill 不保存长期事实。

2.6 Tools 层

文件：

• tools/*.py

用途：本地一次性执行索引、搜索、联想、图谱、trace、评估和 UPSERT，不作为事实源。

2.7 Eval 层

文件：

• eval/README.md
• eval/trace_schema.json
• memory_scaffold_evaluation_policy.md

用途：评估 skill 和 memory scaffold 是否改善任务连续性，避免重复写入、空搜索和无证据结论。

3. 新会话启动规则

1. 读取本文件。
2. 读取 active_task.md。
3. 读取 memory_cards/context_compression_recovery_policy.md。
4. 读取 task_log.md 最近 handoff。
5. 读取 skills/skill_registry.json 或运行 tools/mos_cli.py skill-list，选择当前任务 skill。
6. 运行 tools/make_bootstrap.py "任务关键词"。
7. 如需联想相关经验，运行 tools/associate_memory.py "任务关键词"。
8. 对需要记忆参与的任务，先执行 PLAN：明确要读取哪些记忆、哪些 source_refs 需要验证。
9. 只加载启动包或联想结果中列出的高优先级 memory_cards。
10. 如果需要关键结论，必须打开对应回源入口验证。
11. 任务结束、压缩、暂停或写入前执行 LOG：判断新增经验是否需要 UPSERT 到记忆。

4. 检索规则

检索优先级：

1. memory_card
2. active_task / task_log
3. source_registry
4. 原始文档 chunk
5. 普通配置和低价值短文件

命中后处理：

• 先看 status。
• 再看 source_refs。
• 再判断是否需要回源。
• 不把 inferred 说成 confirmed。

5. 压缩规则

触发条件：

• 工具调用很多。
• 历史上下文明显变长。
• 出现重复问已知信息。
• 当前任务阶段完成或即将切换方向。

压缩前动作：

1. 更新 active_task.md。
2. 在 task_log.md 追加 handoff。
3. 对新增高价值结论更新或新增 memory_cards。
4. 重建索引。
5. 再执行 /compact 或开启新会话。

6. 证据等级

• confirmed：已通过文件、命令、日志、结果或明确文档验证。
• inferred：基于证据的合理推断，但未直接验证。
• proposed：方案、建议或候选路径。
• blocked：因缺环境、权限、资料或用户确认而无法判断。

7. 记忆卡片最小要求

每张卡必须包含：

• ID
• 标题
• status
• domain
• tags
• 结论
• 证据
• 回源入口
• 触发条件
• 不要误用

8. 安全规则

禁止索引和输出：

• API key
• 密码
• token
• 私钥
• 私人备忘文件
• SSH 密码文件
• 远端账号记录文件
• 任何凭据、密钥、token、私有 endpoint 或账号专属路径文件

如任务需要使用凭据，只能从原始凭据源运行时读取，不写入持久记忆。

9. 线程与分支管理规则

• 新任务优先开新线程，不把不同项目和不同目标混进同一上下文。
• 旧任务续做优先使用已有会话或基于 active_task.md、task_log.md、bootstrap 恢复。
• 多个候选方案需要并行探索时，应明确标注为分支探索；失败分支只记录有效结论、失败原因和不要误用，不污染主线叙事。
• 长线程变复杂时优先压缩和写回，不等模型明显遗忘后再补救。

10. 外部资料、MCP 与 Skill 规则

• repo 外、会变化、需要频繁访问、手工复制成本高的信息，优先登记到 source_registry.md 或接入 MCP/稳定检索入口。
• 重复出现两次以上、输入输出清晰、边界稳定的流程，优先沉淀为 Skill、脚本或 memory card。
• 长文档第一次读取后应沉淀摘要和回源入口；原文更新后必须记录旧结论是否失效。
• 不反复把整篇长文档粘进聊天，只加载当前任务必要片段。

11. 多 agent 协作规则

• 只有在用户明确要求子 agent、并行 agent 或委派时才使用子 agent。
• 子 agent 任务必须有清晰边界、输入、输出、文件范围和停止条件。
• 子 agent 返回结果必须包含：完成内容、证据、改动范围、未解决问题和下一步建议。
• 主 agent 负责整合、复核和最终判断，不能把子 agent 结果直接当 confirmed。

12. 架构自优化规则

如果同类问题重复出现两次以上，应判断是否需要升级 MOS 规则、模板、工具或 memory card，而不是只修单次任务。

触发条件：

• 上下文压缩后恢复困难。
• 反复遗漏同一类外部资料。
• 新会话启动找不到最小有效背景。
• task_log 或 memory_cards 不足以支撑继续推进。
• 子 agent 回传内容无法直接集成。
• 同类幻觉、误判或失败路径连续出现。

处理方式：

1. 记录问题和触发场景。
2. 判断是任务问题、资料组织问题、工具问题还是规则问题。
3. 对应更新 AGENTS.md、policy 文件、memory card 模板、工具脚本或 source_registry.md。
4. 在 task_log.md 记录本次规则升级原因和影响范围。