Initial commit
This commit is contained in:
emmettlu
@@ -0,0 +1,154 @@
|
||||
# AgentOS P0
|
||||
|
||||
这是 AgentOS 的第一个可运行单机纵向闭环:
|
||||
|
||||
```text
|
||||
模拟语音文本输入
|
||||
-> 主 Runtime 检索长期记忆
|
||||
-> 本地 NPU 模型提出多个可执行选项
|
||||
-> 用户选择
|
||||
-> Runtime 判断操作是否会重大影响未来时间线
|
||||
-> Btrfs 从同一基点分叉需要执行的世界线
|
||||
-> 本地 NPU 模型生成各世界线的执行计划
|
||||
-> Docker 启动独立 AgentInstance
|
||||
-> 查看结果和文件差异
|
||||
-> 提交, 丢弃或保留分叉
|
||||
```
|
||||
|
||||
## 安全边界
|
||||
|
||||
每个 active AgentInstance 使用独立临时数值 UID/GID. 子 Agent 容器具有以下约束:
|
||||
|
||||
- `--network none`;
|
||||
- 只读容器根文件系统;
|
||||
- `--cap-drop ALL`;
|
||||
- `no-new-privileges`;
|
||||
- CPU, RAM, PID 和文件描述符限制;
|
||||
- 不挂载 Docker socket, 模型目录, 记忆数据库或宿主仓库;
|
||||
- 只读挂载执行计划, 读写挂载专属世界线工作区;
|
||||
- 执行前把专属分叉的所有权移交给临时 UID/GID, 执行结束后完整恢复原所有者;
|
||||
|
||||
Docker 复用物理机内核. Docker 不是业务授权源, 主 Runtime 仍负责选项、记忆和世界线状态.
|
||||
|
||||
## 工作区与回滚
|
||||
|
||||
默认状态目录为 `~/.local/share/agentos`. 当前工作区位于:
|
||||
|
||||
```text
|
||||
~/.local/share/agentos/workspace/current
|
||||
```
|
||||
|
||||
在 Btrfs 上, 每次执行通过可写 subvolume snapshot 创建分叉. 子 Agent 不会直接修改
|
||||
`current`. 提交时旧 `current` 被移动到 `history`, 新分叉切换为 `current`. 丢弃时分叉
|
||||
被原子移动为 `history/<worldline>.discarded`, 当前工作区不变, 后续由受控 GC 物理清理.
|
||||
`:rollback <worldline-id>` 可以恢复该次提交前的完整 Btrfs 状态.
|
||||
|
||||
非 Btrfs 文件系统使用完整目录复制作为功能降级.
|
||||
|
||||
重大操作会为模型给出的 N 个选项建立 N 条世界线. 用户选择的世界线在前台执行并显示
|
||||
完整结果, 其余 N-1 条交给后台 multi 子 Agent 执行. 后台世界线完成后自动保留为 `kept`
|
||||
并只向终端发送完成或失败通知, 不会自动覆盖 `current`. 所有分支都在前台执行前从同一个文件系统基点创建,
|
||||
其 diff 也固定使用该基点, 不受主世界线后续提交影响. 默认后台 worker 数为 4, 可通过
|
||||
`AGENTOS_BACKGROUND_WORKERS` 调整.
|
||||
|
||||
## 本地模型
|
||||
|
||||
默认复用现有模型命令:
|
||||
|
||||
```text
|
||||
/home/emmett/Repos/npu_models/run.sh
|
||||
```
|
||||
|
||||
可通过环境变量覆盖:
|
||||
|
||||
```bash
|
||||
export AGENTOS_MODEL_COMMAND='/path/to/model-command'
|
||||
```
|
||||
|
||||
主 Runtime 在宿主机调用 NPU 模型, token 会实时输出并同时缓存供 JSON 解析. 子 Agent
|
||||
容器不直接访问 NPU. 单块 NPU 的推理调用会串行化, 已生成计划的多个 Docker 子 Agent
|
||||
仍可并行执行.
|
||||
|
||||
模型命令必须支持 `--request-json-stdin`, 并从 stdin 接收:
|
||||
|
||||
```json
|
||||
{"system_prompt":"...","prompt":"...","max_new_tokens":512}
|
||||
```
|
||||
|
||||
因此用户输入和召回记忆不会出现在进程命令行参数中.
|
||||
|
||||
## 长期记忆
|
||||
|
||||
长期记忆保存在 `~/.local/share/agentos/agentos.sqlite3`. 每次模型推理都会重新执行以下链路:
|
||||
|
||||
```text
|
||||
当前用户输入 + 已选方案 + 世界线状态
|
||||
-> SQLite FTS/中文子串候选召回
|
||||
-> 相关性 65% + 重要性 20% + 时间新鲜度 15% 排序
|
||||
-> 按条数和 token 预算裁剪
|
||||
-> 生成带 current_time/memory_id/kind/timestamp 的动态 system context
|
||||
-> 生成逐级减少低相关记忆的 system context 候选
|
||||
-> 由 Qwen tokenizer 精确选择不超过 NPU 1024 token 限制的最大候选
|
||||
-> 通过独立 system role 调用 NPU 模型
|
||||
```
|
||||
|
||||
默认最多召回 6 条、占用约 320 token, 可通过 `AGENTOS_MEMORY_RECALL_LIMIT` 和
|
||||
`AGENTOS_MEMORY_TOKEN_BUDGET` 调整. 只有已提交世界线的执行经验会进入 active 长期记忆;
|
||||
丢弃、失败和回滚的记录仍保留审计数据, 但不会再被召回.
|
||||
|
||||
若去掉全部记忆后任务提示仍然超限, NPU 适配器会保留提示开头和末尾并仅截断中间部分.
|
||||
因此 JSON 输出约束仍会保留, 超限也不会再产生 Python traceback.
|
||||
|
||||
## 开发
|
||||
|
||||
```bash
|
||||
PYTHONPATH=src uv run python -m unittest discover -s tests -v
|
||||
uvx ruff check .
|
||||
uvx ruff format --check .
|
||||
```
|
||||
|
||||
离线冒烟模式不调用 NPU:
|
||||
|
||||
```bash
|
||||
PYTHONPATH=src uv run python -m agentos.cli \
|
||||
--fake-model \
|
||||
--once '记录第一条输入' \
|
||||
--choice 1 \
|
||||
--decision commit
|
||||
```
|
||||
|
||||
## 部署
|
||||
|
||||
```bash
|
||||
./deploy/install.sh
|
||||
```
|
||||
|
||||
安装脚本会安装并启动 Docker, 将当前用户加入 `docker` 组, 构建
|
||||
`agentos-worker:0.1.0`, 然后使用 `uv tool` 安装 `agentos` 命令. 首次加入 Docker 组后
|
||||
需要重新登录. 当前会话可用 `sg docker -c 'agentos --fake-model ...'` 验证.
|
||||
|
||||
交互启动:
|
||||
|
||||
```bash
|
||||
agentos
|
||||
```
|
||||
|
||||
命令:
|
||||
|
||||
```text
|
||||
:history
|
||||
:jobs
|
||||
:memory [query]
|
||||
:forget <memory-id>
|
||||
:rollback <worldline-id>
|
||||
:workspace
|
||||
:quit
|
||||
```
|
||||
|
||||
## 当前 P0 边界
|
||||
|
||||
- 输入源是终端文本, 语义上视为未来 ASR 的 transcript. 交互行编辑支持中文宽字符.
|
||||
- 子 Agent 执行模型生成的非交互 Bash 脚本.
|
||||
- Runtime 与模型之间目前使用单次进程调用, 后续可替换为常驻模型服务.
|
||||
- 外部网络和现实副作用尚未开放.
|
||||
- 长期记忆包含已提交执行经验和模型生成的低权重备注, 支持动态 system context 和 forget.
|
||||
Reference in New Issue
Block a user