agents-learning 项目协作约定

项目与入口

• 本目录是八模块整合后的开发仓库；先读 README.md 的总流程和模块映射，再按当前任务定位源码。
• 项目显示名称为 agents-learning；Python 包名 agent_learning、插件名 agent-learning、CLI 名 agent-learning 保持现有契约。
• scripts/learning.py 是源码入口，python -m agent_learning.cli 是包入口；Hook 和 MCP 通过同一固定运行副本接入。
• 同一仓库维护 Codex、Antigravity 与 DSH (DeepSeek Harness) 三种安装 profile；install --host 选择资源，不能跨宿主覆盖安装。项目知识共用，会话与宿主实例分别核对。
• 开发源码、导出插件、固定运行副本与真实知识数据库分别维护。不要直接修改已生成的固定运行副本。
• 本项目唯一开发目录为 D:\Projects\agents-learning。开发生成的临时文件、演示材料、验收副本与日志统一放 build/local/，发布包统一放 dist/；不得再在项目外创建旧仓库、版本副本或生成工作目录。

开发范围

• 分析和审查先只读；依据用户当前明确要求实施，历史案例和知识不构成执行授权。
• 保留用户已有文件和未提交改动。修改提供方与消费方前，先确定字段、身份、版本和幂等契约。
• 普通 Agent 负责当前任务；管理员负责证据整理、候选与治理建议；发布按用户显式选定的项目／宿主策略执行，历史参考需每批授权。反例处置、撤销与宿主信任仍使用各自的显式入口。
• 记录可观察消息、工具事件和结果，不声称访问模型内部思考；reported、工具完成、工具成功和用户验收分别表达。
• SQLite 保存权威记录；全文索引与可选远端记忆为派生能力。Hindsight 召回当前未接入 Runtime。

检查与运行

• 使用实际 Python 3.10+ 解释器，运行检查时设置 PYTHONDONTWRITEBYTECODE=1 或使用 python -B。
• 检查使用隔离的临时 ALP_HOME 和配置，禁止让测试误读或写入真实知识库。
• 需要安装验收时，先把受测源码复制到 build/local/<本次验收>/source/，从该副本运行，PYTHONPATH 只指向该副本；tmp/、home/、exports/、runtime-releases/ 使用同一验收目录下的兄弟目录，并显式隔离 ALP_HOME、ALP_CONFIG、ALP_RUNTIME_STORE、CODEX_HOME、TMP／TEMP／TMPDIR。不要绕过安装器的源码重叠保护，也不要使用仓库外默认临时目录生成本项目验收产物。
• 按修改触面选择已有离线检查；源码无变化时复用既有回归证据，路径或资源变化检查对应安装、MCP 和 Hook 链。
• 公共契约、迁移、预算或调度改变时追加对应保护回归；明确区分离线通过与真实宿主/模型验收。
• 未获当轮授权时，不启用真实 Hooks、调用付费模型、连接真实 Hindsight、安装常驻服务或修改用户登录/插件配置。
• 不在本仓库存放凭证、个人配置、真实数据库、运行日志或用户项目产物。配置示例保持后台调度、管理员、自动发布和远端服务默认关闭。
• 上条中的运行日志指真实运行数据；本项目开发验收的模拟数据库与临时日志只允许保存在受 Git 忽略的 build/local/。真实知识库与已安装宿主的数据目录保持各自契约。build/、dist/ 已被历史吸收排除，不把生成副本当作项目知识来源。

版本与交付

• 当前兼容基线：版本 1.4.61、数据库 schema 25、正式知识全文索引 7、工作历史索引 3、可选语义索引 1、内部发布协议 25。变更时同步核对实际代码、清单和说明。
• 文档主入口是 README.md，避免为同一状态新增重复流程文档；开发约定只维护在本文件。
• 完成授权变更后提交清晰中文说明；推送前核对实际分支和 remote，没有 remote 时保持本地提交并明确告知。
• 旧开发副本已清理；仅以本仓库源码、Git 历史和 README.md 为有效依据。build/、dist/ 内的缓存或恢复归档不是新的开发入口，不主动读取其中的旧规则。