# artifacttrace

**Repository Path**: shuhui_pku/artifacttrace

## Basic Information

- **Project Name**: artifacttrace
- **Description**: **ArtifactTrace**（小蜗牛）🐌 是一个 artifact-first、trace-native 的 AI/Agent 运行框架。
核心理念：走过即留痕 —— 让每次执行都沉淀为可追溯、可复用的文件产物。

- **Primary Language**: Rust
- **License**: MulanPSL-2.0
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 2
- **Created**: 2026-07-07
- **Last Updated**: 2026-10-11

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# ArtifactTrace

> 一个面向文件中心任务、基于原生 trace 的多智能体 LLM 框架。
> A file-centric, trace-native multi-agent LLM framework.

ArtifactTrace 面向由文件、目录和中间工件驱动的复杂任务：文档整理、代码修改、目录重构、产物生成，以及多个 Agent 跨 Run 的接力协作。

在这类任务中，真正重要的往往不是"谁说了什么"，而是：

- 哪些文件被读取了
- 哪些文件被修改了
- 最近产生了哪些分析结果和共享工件
- 当前工作区现在是什么状态
- 哪些历史观察在文件更新后已经失效

为此，ArtifactTrace 采用两条核心设计原则：

- **File-Centric**：上下文围绕文件、目录和共享工件组织，而不是围绕聊天消息组织；
- **Trace-Native**：上下文直接建立在 run 的原生执行 trace 上，包括文件读写、工具调用和中间结果。

内建 Agent 使用 **8 层 Prompt 架构**：

1. **Identity**：`AGENTS.md` 与 `TOOLS.md`
2. **Team Context**：可协作 Agent 与委派权限
3. **History Summary**：经 compact 的早期历史摘要
4. **Recent Conversation**：近期 Run 消息
5. **Task Context**：`TASK.md`、Skill 摘要与局部任务定义
6. **Environment**：工作目录、时间与 UI 元数据
7. **Working Set**：当前相关文件和选区
8. **User Request**：当前用户请求

详见 [Prompt Build 架构](docs/tech/promptBuild/overview.md)。外部 Agent runner 使用独立且向后兼容的文件/环境变量协议，并不是这 8 层的逐项复制。

此外，ArtifactTrace 采用的是一种 **Stable Agents + Dynamic Skills** 的组织方式：

- agent 是按工具能力划分、长期稳定存在的"施工队"；
- skill 则围绕具体 task 动态检索、生成和注入。

这使系统既保留了稳定的协作边界，又能适应不同任务的特殊需求。

## Why this project?

许多现有 agent 框架更适合"场景驱动的会话任务"，而 ArtifactTrace 关注的是**文件中心、可追踪、可复用、可续接**的工作流。
它特别适合：

- 文档阅读、改写与整理
- 代码 / 配置文件修改
- 目录结构清理和产物生成
- 多 agent 接力的文件协作流程
- 需要跨 run / 跨 agent 复用文件分析结果的任务

## 快速启动

### 发行包

解压对应平台的发行包，确认 `.at/settings.json` 存在，然后运行：

```bash
# macOS / Linux
./scripts/start.sh

# Windows
scripts\start.bat
```

服务监听地址由 `.at/settings.json` 的 `api.host` / `api.port` 决定，模板默认端口是 `8080`。发行包自 v0.8.5 起包含 Node.js 与 Playwright 运行时；浏览器/CDP 依赖见 [README.dependencies.md](README.dependencies.md)。

### 源码开发

需要 Rust toolchain、pnpm 和 Node.js。先构建前端，再启动后端：

```bash
cd frontend
pnpm install
pnpm build
cd ..
cargo run -p artifacttrace-cli --bin at -- serve -s templates/at-template/.at/settings.json
```

前端构建产物由同一个 HTTP 服务提供。开发时也可运行 `pnpm dev`；此时应让 Vite proxy 端口与后端端口一致。

### 运行形态

- Web SPA：后端直接提供 `frontend/dist` 和 HTTP/WebSocket API。
- Tauri 桌面壳：位于 `frontend/src-tauri`，复用同一前端。
- Docker：使用仓库的 `build-docker.sh`、`Dockerfile.template` 和 `docker-compose.yml`。

### Workspace 最小结构

```text
workspace/
├── .at/
│   ├── settings.json
│   ├── persistent_services.json
│   ├── state.db
│   └── task_status.jsonl
├── agents/{agentId}/
│   ├── agent.json
│   ├── AGENTS.md
│   ├── TOOLS.md
│   └── run/{runId}/trace.jsonl
├── tasks/{taskId}/
│   ├── TASK.md
│   └── .at/
│       ├── run/{runId}/trace.jsonl
│       ├── versions/
│       └── external_agents/
├── skills/
├── templates/
└── external_agents/
```

完整说明见 [Workspace 目录结构](docs/tech/backend/Workspace.md)。

### 浏览器操作依赖

如需使用浏览器操作功能（Playwright MCP），请参阅 [README.dependencies.md](README.dependencies.md)。

### 访问界面

| 地址 | 说明 |
|------|------|
| http://127.0.0.1:8080 | 默认界面 |
| http://127.0.0.1:8080/health | 健康检查 |

首次打开后配置模型 Provider、模型和 Agent 默认模型。设置可通过界面或 `.at/settings.json` 管理。

## Changelog

### v0.9.2 (2026-08)

**移动端 /m 完善**
- MChat：历史聊天记录（runs.list → parseTraceEventsToMessages，切任务/agent 自动加载，群聊合并全任务 run）；@ 弹出选人菜单（内部+外部合并候选、键盘导航、IME 兼容、多目标逐个 runs.start）
- MChat：外部智能体列表显示实例名（agent_id），与桌面 AgentStatusBar 一致；选中本地 CLI 型（claude/codex）自动内嵌终端（复用 TerminalTab + external_agents.open_terminal，PTY 保活），终端 ⇄ 聊天可切换
- MChat：localStorage 记住上次选的任务与智能体（独立 key，刷新自动恢复，失效自动回退）
- MFiles：任务顶部 Select 快速切换 + 独立 localStorage 记忆；裸 /files 自动跳入上次任务
- MFiles：文件下载（列表行内 + 预览页，任意类型）；PPTX/DOCX 预览（复用桌面渲染组件）、PDF 浏览器原生预览；MD 预览 ⇄ 编辑（PUT 保存）
- 修复：任务列表点击进不去（navigate 多带 /m 前缀被 HashRouter 兜底弹回）

---

### v0.9.1 (2026-08)

- 修复工具调用 duplicate-key 告警（runner 残留轮重放 + run 认领 dedup）
- 工单路由无匹配时给出「新建任务」建议卡，可建任务并派发；卡片内也可直接新建任务
- 修复工单空路由时无入口可操作的死胡同
- 修复工单产物列表为空的问题，并支持标记/取消标记 Artifact

---

### v0.9.0 (2026-08)

**Native Transcript → trace.jsonl 管线**
- 以外部智能体本地会话文件为事实源产出 `trace.jsonl`，不走 PTY 输出解析；按游标增量读取可见 Turn，幂等导入 + 原子物化，token_usage 一并提取

**Subagent transcript → 子 Run 嵌套**
- `local_sessions` 进入 `subagents/` 发现子智能体 transcript，读旁车 `.meta.json`（toolUseId / spawnDepth / agentType）
- 两遍导入：先顶层（root），再 subagent；`parent_run_id` / `root_run_id` / `depth` / `run_mode="subagent"` 贯穿全栈
- 派生 `agent_id`（`claude_adx1_xxxx`），子 run 在群聊作为独立智能体可见，头像按自身 id 生成
- 幂等：subagent dedup key `(claude, agentId, turn_id)`，重复 `scan_local` 不产生重复子 run

**工单（Work Order）**
- 新增 `work_orders` 模块（api）+ HTTP 路由；按根 Run 收集整条执行链（根 + 委托/回传子节点）
- 前端 `WorkOrders` / `WorkOrderDetail` 页 + `WorkOrderRunCard` + `workOrdersApi`
- `get_runs_by_root_run_ids` 索引查询入口

**Context Checkpoint（Run 内上下文压缩）**
- agentic loop messages 累积超软限时，LLM 生成语义交接，清旧 body 留 frozen prefix + checkpoint continuation，不创建新 Run、不丢审计 trace
- 新增 `context_checkpoint_created` trace 事件工厂

**RunRegistry per-task 聚合**
- `TaskContext`：把原按 task_id 切片散在 runs / agent_queues / task_subscribers 三张全局 map 的状态聚合成 per-task 结构，各字段独立 RwLock，不同 task 互不争锁

**noVNC 反向代理**
- `/browser/viewer/*` 代理到 chrome 服务的 `viewer.internalEndpoint`：HTTP 用 reqwest 转发，WebSocket 用 actix_ws + tokio-tungstenite 双向转发
- 由 chrome 服务 `viewer` 子配置驱动，无 chrome 或 `enabled=false` 返回 404

**一键 YES 提示识别（分层按行）**
- 基于 21 条真实日志误触分析：负层 BUSY（末行工作指示 → 绝不发）→ 结构层 STRUCT（高精度整 tail）→ 关键词层 KW（只对末行匹配，中文从严需确认 affordance）
- 前端 `autoYesRules`（纯函数 + 固件单测）+ `autoYesStore` + `AutoYesLogTab` 命中日志

**前端外部智能体头像修复**
- 外部智能体不在 `agents: Agent[]` 列表（缺 toolPermissions/metadata），群聊头像 fallback 到 `externalAvatarFor`（FNV-1a hash → 30 emoji 池）
- runSlice / feedSlice / historySlice / runFeedParser / traceEventParser 全部解析点补 fallback

**其他**
- MCP http_transport 重构；`persistent_services` 扩展（chrome viewer 子配置）
- ImagePreviewTab / TerminalTab / EditorStatusBar 等前端组件增强
- 文档：`workOrderApi.md` / `IndexerSQLite.md` / `WorkOrderDetail.md` + TaskDetail/Tasks 前端文档同步
- 外部智能体编排文档对齐（trace 产出复用 native_turn_sync 管线，不新写 PTY→trace 转换器）

---

### v0.8.9 (2026-07)

**常驻服务启动统一到 portable_pty**
- Chrome：`nohup detach` → `portable_pty`（自动 setsid 独立存活 + 实时日志 + PID 直取 + 优雅停止），移除 lsof 端口反查与手动 ToolContext 构造
- Daemon：阻塞式 `execute_with_pty`（原 timeout 后误杀常驻进程）→ 非阻塞 `spawn_daemon_pty`
- 新增 `spawn_chrome_pty` / `spawn_daemon_pty`（executor）+ `new_for_daemon` ToolContext 构造

**MCP stdio 三流日志**
- 捕获 stdin（框架请求）/ stdout（JSON-RPC 响应）/ stderr（错误）写入 ToolContext
- 前端 `TerminalTab` 只读展示，三流彩色区分（绿 `→` / 青 `←` / 红 `!`）

**前端终端组件统一**
- `TerminalTab` 成为唯一创建 xterm 的组件，4 处复用（MultiTabEditor / ServiceTab / ExternalTerminalPanel / SubprocessSettings）
- SubprocessSettings 删除重复的 TerminalPanel（~240 行），新增 `ServiceTab`（常驻服务 header + 只读终端）

**后台进程入口（BackgroundProcessesButton）**
- 分类点击：本任务进程 / 本任务外部智能体 / 常驻服务 / 其他任务
- 外部智能体点击跳转任务并自动打开终端；非本任务弹提示切换

**Tab 优化**
- 同名文件父目录区分（`step3/TASK.md`），非根文件始终带父目录（稳定可区分）
- 修复 tab 溢出估算（匹配 CSS `max-width`，避免过早出现 `«`）
- 空状态（tab 全关）保留收缩按钮

**其他修复**
- 修复 `external_agent_terminal` 无法 cancel（补 cancel_callback kill pid）
- 版本历史时间戳改为本地时区友好格式
- 后台进程弹窗加 X 关闭按钮

---

### v0.8.8 (2026-07)

**Docker 构建体系（镜像与运行环境分离）**
- 新增 `build-docker.sh`：配置化构建（`docker-build.yaml` 选 agents/skills/external_agents + 目标架构）
- **at-base 镜像**：只含系统依赖（ubuntu + python3/wget/curl/...），build 一次，长期不变
- **at/ 外挂**：workspace（二进制 + 前端 + 配置）通过 docker-compose volumes 映射，日常迭代 scp + restart 即可
- 交叉编译 linux x64（cargo-zigbuild），mac 组装 → scp → 服务器 build
- 新增 `Dockerfile.template`（模板渲染）+ `docker-compose.yml`
- 新增 `download-at-deps.sh`：下载 node 4 架构到 `~/GitRepo/at-deps/node_deps/`
- skills 外挂源（`at-deps/localskill`），不打包进 template

**文件版本记录修复**
- 修复内置 agent 新文件不被版本记录的问题（side_effect 驱动 `get_side_effect_files`）
- 新增外部 agent 版本记录（扫描 task_dir 比 hash，`scan_and_commit_changed_files`）
- 版本记录忽略 `.playwright-cli/`（避免 web agent 运行时刷屏 + 无意义版本）
- blob GC：`BlobStore::gc()` + HTTP API `POST /api/tasks/{taskId}/versions/gc`

**FileTree 修复**
- `file_watcher` 排除 `.playwright-cli/` / `node_modules/` / `target/` 等（不再刷屏）
- 前端 `filterTree` 始终过滤运行时目录（无搜索时也生效）
- 前端 tab 溢出折叠菜单（« 下拉，含直接关闭）
- 前端 RunFeedCard 展开显示完整内容（修复数据层截断 bug）
- 前端 PPT 预览 Strict Mode 页数翻倍修复
- 前端 Web external agent 对话框修复（不再报 open_terminal，显示输入框）

**qwen-chat runner.sh**
- 修复 macOS BSD sed 兼容（`sed -e '1d' -e '$d'` 替代 `sed '1d;${d}'`）
- 上传流程改为「添加附件」→「上传文档」菜单（UI 升级适配）

---

### v0.8.7 (2026-07)

**外部智能体流式输出优化**
- 新增 `StreamOutputParser`：Rust 端实时解析 codex JSONL / claude 文本输出，转为统一的可读片段（`message` / `action` / `result` / `thinking` / `error`），前端不再看到原始 JSON
- runner.sh（codex / claude）改用 `tee` 让 stdout 流向 PTY，实现真正的流式进度展示
- 前端外部智能体输出改为分段样式化渲染：命令用等宽块、结果用代码块、思考用灰色斜体，不再堆成一长串
- PTY 超时自动延长：外部智能体持续有输出时，超时自动延长（每次 +60s，最多 10 次），避免长任务被误杀

**外部智能体会话事件**
- 新增 `session_initialized` / `session_destroyed` 事件：外部智能体加入 / 离开群聊时显示系统通知
- init 操作现在也会写入 `trace.jsonl`，保持 run 目录结构一致
- TraceWatcher 支持转发会话事件

**消息修复**
- 修复与外部智能体对话时 `...` 占位符永久残留的问题

**预览修复**
- 修复 PPT 预览在开发模式（React Strict Mode）下页数翻倍的问题

---

### v0.8.6 (2026-07)

**群聊与消息**
- 群聊默认智能体改为 per-task，自动取上一条消息的首个 @
- 修复 MessageList 消息排序与流式终态一致性问题

**文件树增强**
- 新增从剪贴板粘贴文件到文件树（右键菜单）
- 右键菜单新增「在文件夹中打开」(Reveal in Finder / Explorer)
- 三区域折叠交互一致性优化、ContextMenu 智能定位、搜索框样式优化

**其他**
- external agent runner.sh 统一用 `${VAR}` 规避 macOS bash 3.2 的 UTF-8 bug
- 新增本地构建脚本，简化模板配置

---

### v0.8.5 (2026-06)

**bundled Node.js & Playwright**
- 打包 Node.js 与 Playwright 运行时，CLI 部署无需本地安装 Node 环境
- Web agent 不再因 `playwright-cli` 缺失而静默失败

**TaskChannel 滚动优化**
- 任务通道滚动行为与性能优化

**OAuth 修复**
- OAuth redirect URI 改用 `localhost`（替代 `127.0.0.1`）
- OAuth redirect 端口调整为 8868

---

### v0.8.0 (2026-05-26)

**MCP 协议修复**
- 修复 MCP `roots/list` 请求无响应导致的工具调用超时
- 现在正确响应 `roots/list` 并返回实际 workspace 路径
- 解决 Playwright MCP 等需要 workspace roots 的 MCP server 首次调用卡死问题

**浏览器进程独立化**
- Chrome 浏览器子进程现在独立于主进程运行
- 主进程退出时浏览器保持运行（使用 shell double-fork 技术）
- 新增 `start-chrome-debug.sh` 脚本用于手动启动调试浏览器

**Shell 工具 PATH 修复**
- Shell 工具现在使用与 MCP stdio transport 相同的 PATH 加载算法
- GUI 模式下正确找到 `npx`、`node` 等命令（解决 bundled Node.js 路径问题）
- 支持从 shell profile (`~/.zshrc`, `~/.bash_profile`) 加载环境变量

**Chrome 调试端口调整**
- 默认调试端口从 9223 改为 9222（与 Chrome 默认一致）
- 前端 chromeStore 和后端 chrome.rs 统一端口设置

**界面微调**
- 输入框最小高度从 22px 增加到 44px，改善输入体验

---

### v0.7.0 (2026-05-22)

**文件树拖拽移动**
- 新增拖拽移动功能，支持文件/文件夹拖拽到目标目录
- 拖拽时源节点半透明，目标文件夹蓝色虚线边框高亮
- 支持拖拽到根目录、嵌套文件夹
- 防止非法操作（拖到自己子树、同名冲突等）
- 移除右键菜单中的"移动"选项（使用拖拽替代）

**智能体模型选择器**
- 每个智能体可独立选择默认模型
- AgentListItem 和 ExternalAgentMenu 新增模型选择下拉按钮
- 修复下拉菜单同时打开多个的 bug（全局协调机制）
- 后端优先使用智能体的 default_model，空字符串时回退到全局设置

**代码重构**
- 大文件拆分以符合项目规范（单文件 <800 行）：
  - external_runner_driver.rs (1319行) → 5 个文件
  - prompt_build.rs (1018行) → 3 个文件
  - external_agents.rs (918行) → 5 个文件
  - callagent_handler.rs (901行) → 5 个文件

**后端优化**
- 新增 HTTP 文件移动 API：POST /api/files/{task_id}/move
- 优化日志输出，减少冗余 DEBUG 日志（16184 条降至合理数量）
- ping 消息改为 DEBUG 级别

---

### v0.6.0 (2026-05-09)

**文件预览支持**
- 新增图片预览功能（png、jpg、jpeg、gif、bmp、ico、svg、webp）
- 新增 PDF 文档预览功能
- 新增表格预览功能（xls、xlsx、csv），使用 SheetJS 解析，支持多 Sheet 展示
- 扩展 FileType 分类系统，新增 image、document、spreadsheet 类型

**外部 Agent 支持优化**
- AgentStatusBar 正确处理 runs.start 返回消息，实时显示外部 Agent 运行状态
- 新增 external_agent_queue_updated 事件订阅，支持队列状态更新
- 支持外部 Agent 的 runs.cancel_queued 操作

**编辑器改进**
- Monaco 编辑器使用等宽字体（Menlo、Monaco、Consolas 等），改善代码对齐
- 修复 localStorage 缓存的 fileType 在页面刷新后不重新检测的问题

**文件树交互优化**
- 新增 isViewableFile 函数，支持可预览文件（图片/PDF/表格）的点击打开
- HTTP API 为预览文件类型添加正确的 Content-Type 响应头

---

### v0.3.0 (2026-04-08)

**流式进度优化**
- 新增 `tool_call_chunk` 事件类型，实时显示工具调用构造进度
- 前端显示 "🔧 正在构造 tool_name..." 进度提示
- 修复 LLM 流式响应时显示空消息气泡的问题

**Tool Call ID 优化**
- 使用 UUID 作为 `tool_call_id`，避免重复 ID 导致的进度消息重复

**LLM 流式修复**
- 修复 OpenAI 流式调用超时错误（移除 total timeout，保留 connect_timeout）
- 增强大文件场景下的上下文管理，避免溢出问题

**前端改进**
- Task 列表页改进浏览体验
- 编辑器多标签页优化
- 文件树交互改进

---

### v0.2.0 (2026-04-07)

**架构优化**
- 实现 Five-Layer Context Architecture，将 prompt 分层构建：
  - Layer 1: 身份规则 (AGENTS.md + TOOLS.md)
  - Layer 2: 历史摘要 (History Summary)
  - Layer 3: 近期历史 (Recent History)
  - Layer 4: 当前环境 (Working Directory + UI Context)
  - Layer 5: 用户问题 (User Message)
- Active File 注入格式改为 JSON fenced code block，避免嵌套内容问题

**Trace 优化**
- 修复 `tool_call_completed` trace 记录不完整的问题
- 现在正确记录 `input_files`（读取的文件）、`output_files`（写入的文件）、`modified_files`（修改的文件）
- 支持正确的 `ref_type`: `read`, `write`, `modify`

**跨平台支持**
- 添加 Windows 编译支持 (`x86_64-pc-windows-gnu`)
- Shell 工具适配跨平台：Unix 用 `sh -c`，Windows 用 `cmd /C`
- 修复 `process_group` 等 Unix 特有 API 的跨平台兼容性

**前端改进**
- 文件树添加 VSCode 风格的垂直缩进线
- 文件图标与目录箭头对齐
- 修复嵌套文件夹显示问题

**集成能力**
- 初步支持 Chrome 浏览器 skill（远程调试协议）
- stdio 模式的 MCP client，支持工具动态注册

---

### v0.1.0 (2026-03)

**初始版本**
- 基础 Agent / Task / Run / Step 执行模型
- WebSocket API 支持
- 基本的 trace 记录
- 前端 React 应用