# 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/` 内的缓存或恢复归档不是新的开发入口，不主动读取其中的旧规则。