Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
14 changes: 7 additions & 7 deletions AGENTS.md
Original file line number Diff line number Diff line change
@@ -1,14 +1,14 @@
# Iris 后续实现说明

产品行为以 `companion_memory_cognition_system_design_integrated.md` 和 `DECISIONS.md` 为准。M1 已于 2026-10-08 完成(DECISIONS.md「M1 完成」),M2 已于 2026-10-09 完成(DECISIONS.md「M2 完成」,含已知问题);M3 已于 2026-10-10 完成(DECISIONS.md「M3 完成」,persona 与记忆合并的隐藏集门槛列为已知问题,persona 默认全部人工确认);M4 已于 2026-10-10 完成(DECISIONS.md「M4 完成」,“不需要人工干预”按用户决定改为上线测试后分析运行日志,persona 优化线暂停);设计 22 的阶段全部完成;2026-10-11 合入上线前修复、定时备份、管理页批量遗忘/删除和入口画像(DECISIONS.md 2026-10-11 各条),当前为上线测试:用户以 AstrBot 插件接入真实聊天平台,测试结束后用 iris-connectors 的 `tools/live_review/` 读取运行记录(README「运行记录」)分析。2026-10-11 起按用户决定补做为上线搁置的事项,现状见 DECISIONS.md 2026-10-11「上线后补做搁置事项」及 2026-10-12 各条(学习默认为 v10;人物摘要默认 v2 并按条裁剪超限;入口画像已改为主题化记忆与每日增量观察(#112—#115、#117),#116/#126/#127 均未超过 main 已关闭,小改动暂停,按调研结论先重建公开 dev 集并验证“发现”改法;persona 优化线 #61 作为改进合并、默认仍全部人工确认;整理请求预算 180 秒;目标去重默认 D6)。2026-11-10 起进入全自动阶段,各线内容、门槛和顺序见 DECISIONS.md 2026-11-10「全自动阶段计划」;2026-11-11 整理自动处理通过门槛并默认开启(#139、#140),persona #133 作为改进合并,见 DECISIONS.md 同日条目。M4 的计划、门槛口径和对照规则见 DECISIONS.md 2026-10-10「M4 计划」及 `evals/README.md`「M4 计划」。M3 的计划见 DECISIONS.md 2026-10-09「M3 计划」及 `evals/README.md`「M3 计划」。M2 的计划见 DECISIONS.md 2026-10-08「M2 计划」及 `evals/README.md`「M2 计划」。当前代码完成 M1 学习核心、召回与宿主接口,以及后台调度、模型用途暂停恢复、向量补算、HTTP 立即学习和端到端评测;本机试用对话、记忆管理和运行状态界面,首次设置、管理员会话、设置页和 secrets.json 已实现;M2 的生命周期与每日维护、回复准备的召回判断、人物联系的确认/否认/合并、高流量入口过滤及其界面已实现;宿主令牌、入口可见范围、媒体与图片理解、导出导入、接口 v1 冻结和运行记录已在 M4 实现,接入示例与 AstrBot 插件在 iris-connectors 仓库。不要复制 `dev-0`、`dev-1` 分支的代码。
产品行为以 `companion_memory_cognition_system_design_integrated.md` 和 `DECISIONS.md` 为准。M1 已于 2026-10-08 完成(DECISIONS.md「M1 完成」),M2 已于 2026-10-09 完成(DECISIONS.md「M2 完成」,含已知问题);M3 已于 2026-10-10 完成(DECISIONS.md「M3 完成」,persona 与记忆合并的隐藏集门槛列为已知问题,persona 默认全部人工确认);M4 已于 2026-10-10 完成(DECISIONS.md「M4 完成」,“不需要人工干预”按用户决定改为上线测试后分析运行日志,persona 优化线暂停);设计 22 的阶段全部完成;2026-10-11 合入上线前修复、定时备份、管理页批量遗忘/删除和入口画像(DECISIONS.md 2026-10-11 各条),当前为上线测试:用户以 AstrBot 插件接入真实聊天平台,测试结束后用 iris-connectors 的 `tools/live_review/` 读取运行记录(README「运行记录」)分析。2026-10-11 起按用户决定补做为上线搁置的事项,现状见 DECISIONS.md 2026-10-11「上线后补做搁置事项」及 2026-10-12 各条(学习默认为 v10;人物摘要默认 v2 并按条裁剪超限;入口画像已改为主题化记忆与每日增量观察(#112—#115、#117),#116/#126/#127 均未超过 main 已关闭,小改动暂停,按调研结论先重建公开 dev 集并验证“发现”改法;persona 优化线 #61 作为改进合并、默认仍全部人工确认;整理请求预算 180 秒;目标去重默认 D6)。2026-11-10 起进入全自动阶段,各线内容、门槛和顺序见 DECISIONS.md 2026-11-10「全自动阶段计划」;整理自动处理通过门槛并默认开启(#139、#140)。v0.0.3 已发布,Persona 通过隐藏集门槛并默认自动发布(#141、#143),详见 DECISIONS.md。M4 的计划、门槛口径和对照规则见 DECISIONS.md 2026-10-10「M4 计划」及 `evals/README.md`「M4 计划」。M3 的计划见 DECISIONS.md 2026-10-09「M3 计划」及 `evals/README.md`「M3 计划」。M2 的计划见 DECISIONS.md 2026-10-08「M2 计划」及 `evals/README.md`「M2 计划」。当前代码完成 M1 学习核心、召回与宿主接口,以及后台调度、模型用途暂停恢复、向量补算、HTTP 立即学习和端到端评测;本机试用对话、记忆管理和运行状态界面,首次设置、管理员会话、设置页和 secrets.json 已实现;M2 的生命周期与每日维护、回复准备的召回判断、人物联系的确认/否认/合并、高流量入口过滤及其界面已实现;宿主令牌、入口可见范围、媒体与图片理解、导出导入、接口 v1 冻结和运行记录已在 M4 实现,接入示例与 AstrBot 插件在 iris-connectors 仓库。不要复制 `dev-0`、`dev-1` 分支的代码。

2026-10-05 起,开发与评测的对话模型改为 glm-5.3-flash,开发设备改为 macOS。MiniMax-M3 时期的评测结果全部作废;GLM 重测计划及新设备召回复现见 `evals/README.md`。

## 分工
## 开发与验收

规划者(监督者)负责规划、审查和文档,并在仓库外维护隐藏验收集;执行者负责代码、测试和评测。2026-11-10 起分两类执行者,都由规划者下达任务、审查结果:代码实现、测试和提 PR 由规划者启动的 Claude 子代理完成;生成数据(写语料和隐藏集、运行真实评测)和审查测试数据(判分、审核语料、分析评测材料)由 Codex 会话完成,统一使用 gpt-6.1-sol、推理档位 max。PR 经规划者批准后才 squash 合并,只合并审查过的那次提交,由规划者指定的集成子代理执行;实现该 PR 的执行会话不合并 PR,不直接修改 main。执行者不修改设计文档和 DECISIONS.md;需要改动时在报告中提出,由规划者决定。每个执行任务在自己的 git worktree 中进行。可以同时有多个执行会话。同时修改产品代码(`src/`、`tests/`、迁移和提示词)的会话,改动的文件不能重叠;有重叠就排队,由规划者安排顺序。其余会话只运行评测、整理报告,或做互不重叠的配置。
自 2026-11-17 起,由当前 Codex 会话独立完成规划、实现、测试、评测、审查、文档和集成工作。各项实现按顺序在独立 Git worktree 中进行。提交前审查差异并验证候选版本。主分支通过已批准的 PR 更新,squash 只合并审查过的那次提交。

评测判分由执行者所用的模型按评分说明完成,不调用对话模型;`iris eval learning`/`iris eval e2e` 默认保留内置对话模型判分,只作预览,不作门槛依据。两次判分在互不可见的独立会话中完成,第二次不能看到第一次的结果;用于门槛判定的判分,由没有参与该轮代码和提示词修改的执行会话完成。目前只在 macOS 上验证,暂不做 Windows 验证。
隐藏验收集由维护者在仓库外保管。实现会话使用公开开发集和验收汇总,不寻找或读取隐藏语料。需要双盲判的门槛按冻结评分说明,在两次彼此隔离且均未参与该轮实现的 Codex 会话中完成。两轮分别记录判分模型和推理档位,延续既有门槛的判分使用 gpt-6.1-sol max。对话模型内置判分和当前实现会话的预览只作诊断。当前在 macOS 验证。

## 安装和运行

Expand Down Expand Up @@ -73,7 +73,7 @@ uv run iris eval e2e-score --materials <材料目录> --judgments <第一轮目

`test-models.toml` 含 API key,必须保持在 `.gitignore` 中。不要把密钥写入代码、测试、报告、日志、终端输出、提交或 PR 描述。每次提交前运行 `git check-ignore test-models.toml`、查看 `git diff --cached`,并核查暂存内容不含密钥。若发现密钥已提交或推送,立即停止并通知用户更换,不改写历史。

只在功能分支提交和推送,不直接修改 main,不 force push、不合并 PR。新增行为先有确定性测试或假模型集成测试,再用真实评测检查效果。模型调用必须在数据库事务之外;记忆正文和判断的修改需校验修订号,保留强度使用原子增量,不加修订号。文件和 HTTP JSON 都使用 UTF-8。
只在功能分支提交和推送,禁止 force push。新增行为先有确定性测试或假模型集成测试,再用真实评测检查效果。模型调用必须在数据库事务之外;记忆正文和判断的修改需校验修订号,保留强度使用原子增量,不加修订号。文件和 HTTP JSON 都使用 UTF-8。

## 召回与验证

Expand All @@ -95,7 +95,7 @@ trigram 查询中的一字/两字实词同时查已有 jieba 索引,与三

不能在运行评测时切换或重建同一虚拟环境,也不要在模型评测运行期间修改源码或迁移。完整学习案例按源码/语料/模型端点、ID、维度/判分次数指纹保存在忽略的 `data/lc/<16位指纹>`,meta.json 校验完整 SHA-256;外部 --out 的检查点在 `<out>/.lc/<16位指纹>`,完整明细也留在外部。只复用相同输入的完成案例,不按分数选择或改写结果。

召回验收 R01—R14 均已实现(R02、R03、R14 在 M4)。宿主接口 v1 已冻结,不兼容的修改须先在 DECISIONS.md 记录并经规划者批准;M3 的模型整理、persona、当前状态和目标的现行规则见 DECISIONS.md 2026-10-09 至 2026-10-10 各条。合成性能数据由 `evals/benchmark_retrieval.py` 生成,不属于质量评测语料;加 `--default-config` 测量当前默认的 5 千/5 万条、点名/不点名四组 prepare。
召回验收 R01—R14 均已实现(R02、R03、R14 在 M4)。宿主接口 v1 已冻结,不兼容的修改须先在 DECISIONS.md 记录并经用户批准;M3 的模型整理、persona、当前状态和目标的现行规则见 DECISIONS.md 2026-10-09 至 2026-10-10 各条。合成性能数据由 `evals/benchmark_retrieval.py` 生成,不属于质量评测语料;加 `--default-config` 测量当前默认的 5 千/5 万条、点名/不点名四组 prepare。

## 调度与端到端(M1-6)

Expand Down Expand Up @@ -143,4 +143,4 @@ trigram 查询中的一字/两字实词同时查已有 jieba 索引,与三

## Docker 与发布(2026-10-11)

镜像 `ghcr.io/airobject/iris-core`(Dockerfile、`.github/workflows/release.yml`)。只有环境变量 `IRIS_CONTAINER=1`(镜像内设定)时 serve 才接受非回环监听,配置文件不能开启;镜像默认 `0.0.0.0:8080`、数据目录 `/data`、非 root。部署只映射到 127.0.0.1,或放在可信 Docker 网络并用 `IRIS_ALLOWED_HOSTS` 列出服务名;本服务不提供 TLS。推送 `v*` 标签触发发布:先核对标签与 pyproject 版本一致,再跑两个 Python 版本测试与构建,通过后推送 linux/amd64、linux/arm64 镜像(版本号与 latest)并创建附 wheel/sdist 的 GitHub Release;只用 GITHUB_TOKEN。版本号在 pyproject.toml,`iris --version` 输出。容器相关改动须在本机 Docker 构建并运行验证(设置码、设置、令牌、两种 Host 的 prepare、重启保留数据)。
镜像 `ghcr.io/airobject/iris-core`(Dockerfile、`.github/workflows/release.yml`)。只有环境变量 `IRIS_CONTAINER=1`(镜像内设定)时 serve 才接受非回环监听,配置文件不能开启;镜像默认 `0.0.0.0:8080`、数据目录 `/data`、非 root。部署只映射到 127.0.0.1,或放在可信 Docker 网络并用 `IRIS_ALLOWED_HOSTS` 列出服务名;本服务不提供 TLS。推送 `v*` 标签触发发布:先核对标签与 pyproject 版本一致,再跑 Python 3.13 测试与构建,通过后推送 linux/amd64、linux/arm64 镜像(版本号与 latest)并创建附 wheel/sdist 的 GitHub Release;只用 GITHUB_TOKEN。版本号在 pyproject.toml,`iris --version` 输出。容器相关改动须在本机 Docker 构建并运行验证(设置码、设置、令牌、两种 Host 的 prepare、重启保留数据)。
2 changes: 1 addition & 1 deletion ARCHITECTURE.md
Original file line number Diff line number Diff line change
Expand Up @@ -213,7 +213,7 @@ auto_v1 的初判使用 `consolidation_pair_auto_v1.md`(report_only 仍用 pai

目标阶段每次读取最多 100 个未合并的开放目标及修订;逐目标在自己的短事务调用 `review_goal_basis(conn, current, goal_id=..., expected_revision=...)`,将依据观察、目标历史、报告项和维护游标原子提交。采用目标线的单项事务接口,是为了使报告/游标与目标变化一同回滚;独立的 review_goal_basis_items 仍供其他分页调用者使用。冲突跳过并汇总,下一次从 0 扫描;新目标不越过本次 goal_through 上界。依据恢复/再变化由目标模块结束旧标注,不自动删除或关闭目标,过期标识沿用实时投影。

目标阶段的确定性项目处理完后,按运行时固定的两个开关(`settings_json.goal_auto`,且当前设置仍开启)依次执行 G2 和 G1(全自动阶段 G 线,默认关闭)。两者都是“只读快照取材料 → 事务外调用模型 → 单个短写事务核对修订号并写结果和报告项”:G1 为 `auto_review_material`/`judge_goal_review`/`apply_goal_review`,G2 为 `duplicate_auto_material`/`judge_duplicate_pair`/`apply_duplicate_judgment`。G2 与创建时复核共用 `dedup_review_material`、`dedup_review_decision`、`dedup_review_stale`,因此现有去重探测测到的就是维护路径的判断。指纹表 `goal_auto_reviews`、`goal_duplicate_judgments`(迁移 039)记录已完成的判断,续跑和下一次维护跳过未变化的目标;失败不记指纹。运行统计连同游标写在 `progress_json.goal_auto`,与每项结果同事务提交,续跑从游标继续并累加计数;逐项结果写 `maintenance_items`(phase=goals)。`goals.auto_review_after_message_id` 是管理员重开时的消息水位,之后的候选只取更新的消息,`_merge` 取双方较大值。G1 按最久未复核优先(忽略本次运行自己的判断,续跑顺序不变),跳过本次运行中 G2 刚合并进来的存续目标;“我”的候选消息只取目标所在入口和目标创建之后涉及的人发过言的入口,查询走迁移 039 的 `messages(sender_subject_id,entry_id,id)` 索引。G1 关闭时逐条通过核对的合格依据写入 `goal_auto_review_evidence`,`memory_ops.message_references` 据此保护它们不被消息清理删除,重开时删除这次关闭的保护。G2 按较晚一方的 `host_scope_json` 组材料和合并;较晚一方本身或已被合并进它的任一宿主目标要并进其范围外的目标时只记 kept、保留标记;自动合并在 `goal_duplicate_judgments.merge_record_json` 记下撤销所需的 ID 和字段值(不含正文),`undo_auto_merge` 在核对存续目标修订号后原样退回。
目标阶段的确定性项目处理完后,按运行时固定的两个开关(`settings_json.goal_auto`,且当前设置仍开启)依次执行 G2 和 G1(全自动阶段 G 线,从迁移 042 起默认开启。`AUTO_DEFAULTS` 和设置请求模型的回退值均为开启,迁移给新库和没有任何 `settings_goals` 操作记录的旧库写入开启,有记录的旧库用 `json_insert` 把缺少的开关补成以前的实际值关闭,已写入的值不动)。两者都是“只读快照取材料 → 事务外调用模型 → 单个短写事务核对修订号并写结果和报告项”:G1 为 `auto_review_material`/`judge_goal_review`/`apply_goal_review`,G2 为 `duplicate_auto_material`/`judge_duplicate_pair`/`apply_duplicate_judgment`。G2 与创建时复核共用 `dedup_review_material`、`dedup_review_decision`、`dedup_review_stale`,因此现有去重探测测到的就是维护路径的判断。指纹表 `goal_auto_reviews`、`goal_duplicate_judgments`(迁移 039)记录已完成的判断,续跑和下一次维护跳过未变化的目标;失败不记指纹。运行统计连同游标写在 `progress_json.goal_auto`,与每项结果同事务提交,续跑从游标继续并累加计数;逐项结果写 `maintenance_items`(phase=goals)。`goals.auto_review_after_message_id` 是管理员重开时的消息水位,之后的候选只取更新的消息,`_merge` 取双方较大值。G1 按最久未复核优先(忽略本次运行自己的判断,续跑顺序不变),跳过本次运行中 G2 刚合并进来的存续目标;“我”的候选消息只取目标所在入口和目标创建之后涉及的人发过言的入口,查询走迁移 039 的 `messages(sender_subject_id,entry_id,id)` 索引。G1 关闭时逐条通过核对的合格依据写入 `goal_auto_review_evidence`,`memory_ops.message_references` 据此保护它们不被消息清理删除,重开时删除这次关闭的保护。G2 按较晚一方的 `host_scope_json` 组材料和合并;较晚一方本身或已被合并进它的任一宿主目标要并进其范围外的目标时只记 kept、保留标记,判断函数 `_host_scope_blocks_merge` 由 G2 和创建时复核(`Goals.review` 写回前)共用,后者被拦时不合并、改为可能重复标记(`reason=host_scope_not_merged`);自动合并在 `goal_duplicate_judgments.merge_record_json` 记下撤销所需的 ID 和字段值(不含正文),`undo_auto_merge` 在核对存续目标修订号后原样退回。

`PATCH /admin/api/settings/consolidation` 暴露 max_calls、resolution(默认 auto_v1,可退回 report_only_v1)及 merge_enabled、conflict_enabled、dependency_enabled、persona_enabled、goal_review_enabled(全开),时间复用 lifecycle.maintenance_time;更新与审计同事务。模型项目开关进入候选指纹和待办筛选,关闭期间不消耗该类调用,重新打开可发现延期项目;合并和矛盾共用一轮分类,关闭矛盾建议时仍防止矛盾记忆合并。报告通过原维护接口汇总变化、失败、模型建议、persona 结果、目标复核和全部模型用量;无变化/未到期只汇总,记忆建议始终仅管理员可见。

Expand Down
Loading