Agent-os-open: Instructions file for Codex

灵汐 AgentOS — 项目记忆（供 AI 协作者）

本文件是给在本仓库工作的 AI 代理（DSH 等）的项目上下文。读完它再动手； 口径冲突时以本文件 + docs/decisions/ 为准（README / ARCHITECTURE / guides 已对齐 0.2 现状）。

项目是什么

可进化的智能体操作系统：把 LLM、工具、记忆、任务、配置组织成可观测、可干预、 可回滚的管道（Pipeline）。当前主线为 0.2 架构：Rust 微内核 + Python 插件 + React 前端。

仓库布局（0.2 现实）

路径	内容
kernel/	Rust 微内核（crates：api/config/core/db-admin/engine/hooks/http/invoker/mcp/plugin-loader/session/tenant/user-admin；agentos-kernel 是主进程）
plugins/	Python 插件（shared/system/ 系统插件、shared/tools/ 工具插件、shared/pipeline/ 管道插件）
frontend/src/	React 19 + Vite + Zustand + Antd（RJSF v6 表单引擎）
config/	运行配置（agents/tools/plugins/pipelines/isolation/storage.yaml 等）
docs/	文档；docs/decisions/ = ADR 决策记录；docs/working/ = 工作文档与研究报告
tests/	Python 测试（pytest）；kernel/crates/*/tests/ Rust 测试
scripts/	运维/清理脚本
data/、logs/、reports/	运行时产物

存储：SQLite（默认项目根 agentos_kernel.db），driver 化切换见 config/kernel/storage.yaml（AGENTOS_STORAGE_DRIVER/AGENTOS_DB_PATH 环境变量可覆盖）。

⚠️ 工作区铁律（最重要）

受管开发环境（本仓容器工作区）会被周期性还原到 git HEAD——未提交的改动会被抹掉 （普通 clone 无此行为，但提交纪律通用）。任何修改（含中间产物、测试数据）完成后立即 commit，不要留到"最后一起提交"。commit 前的调查/验证工作尽量用未跟踪文件（?? 状态）或文档目录进行。

架构要点（2026-08 现状）

• 一切皆插件（架构公理，写文档/方案一律以此为基）：内核只是执行基座（管道解释 执行/能力注册表/插件装载/存储），一切能力——LLM、记忆、评估、审批、触发器、通道、 主题、乃至 agent 配置的加载——皆插件承载；改业务行为 = 加/改插件或配置，不动内核。 动因六条（自进化落地/改动半径分离/故障隔离/语言生态自由/统一契约/治理单点）与 能力→插件对照表见 docs/ARCHITECTURE.md 设计哲学 §1。
• 插件即声明：插件 = plugin.json 清单 + Python 实现。capabilities.tools = LLM 工具声明即注册（无需类型豁免）；capabilities.services = 内部服务方法元数据。 工具声明要带 output_schema + render（工具契约，tool_core 校验 fail-closed， 前端按 render 意图路由）。插件放 plugins/shared/{system,tools,pipeline}/<name>/。
• 评估闸门：插件判定，内核只落库：判定逻辑已从内核移出归插件——评估裁决 在 plugins/shared/system/evaluation/（task_evaluate 工具），放行检测在管道 output 步骤 task_reminder（提醒耗尽仍无评估证据 → task.status = pending_evaluation，不落 completed；有证据内核才补落默认 completed）；内核不 做判定，只经 pipeline-state 写面记录结果。agent 配置加载同样已移出内核，由 管道输入插件 agent_config_load 自持（plugins/shared/pipeline/input/agent_config_load/）。
• 任务默认隔离执行：默认工作空间 workspace/{task_id} + isolated。
• 工具面过滤：LLM 可见工具由 config/agents/main/agentos.yaml（及 executor/general_agent.yaml）的 tool_ids 白名单控制，新工具记得加入。
• 权限模式：4 档权限模式（default/accept_edits/auto/bypass，黑名单制：未命中 安全规则的操作任何档位都直接执行）+ 参数级危险判定，纯插件前端 （http_endpoints + form compact + human-interaction 确认）。隔离/worktree 会话 未显式选择档位时默认完全免审批（隔离容器即安全边界，用户裁定 2026-09-15； 该默认由旁路档承载，与显式选旁路同档同路径，OBS-R255-1 2026-09-22 统一）； 显式选 default/accept_edits/auto 三档后以所选档为准（隔离不再豁免黑名单）， 显式选旁路即免审批本身；选择器如实显示当前生效档（未显式选择时隔离/worktree 显示「免审批」，与显式选旁路可辨别）。非隔离会话无免审批默认，按档走。 会话隔离由 isolation_guard 容器落地。
• 插件热发现/热重载全链路：新建插件目录、修改 plugin.json、改插件 Python 代码 均由 watcher 自动处理（发现→G2 校验→注册/重注册/respawn），无需 re-enable 或重启； cdylib 集合变更走 G8 自动重启（同 id 换产物保守重启）；已知插件面取自共享 manifests 活集合（新插件热注册后管道引用即可编译）；前端 schema 需刷新页面才更新。
• 多循环体/执行上下文：execution_context 贯穿任务链；agent_id 的本质是执行上下文 键——内核无 Agent 运行时对象，语义由插件按键展开（agent_config_load 按键加载配置， 工具面 tool_ids 同属这份执行上下文，与提示词同源注入）；内核零 agent 配置 知识（不读 config/agents/**）——工具面过滤 = tool_schema 插件读 state.tool_ids 经内核 tool-surface capability 服务完成（ADR 2026-09-02）。