wuyang/zk-data-agent
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

add docs

Browse Source
This commit is contained in:
武阳
2026-04-24 10:33:15 +08:00
parent b521d6ce29
commit fed0999f55
4 changed files with 1893 additions and 2055 deletions
Download Patch File Download Diff File Expand all files Collapse all files
CLAW_AGENT_ARCH_ANALYSIS.md
-933
View File
@@ -1,933 +0,0 @@
# Claw Code Agent 架构逆向分析报告
本文基于只读分析仓库源码撰写，目标不是介绍如何使用，而是回答这个项目作为一个 Agent 系统是如何被构造出来的。
---
## 1. 总体定位
### 1.1 这个项目本质上是什么
这个项目本质上是一个 **agentic coding runtime**，而不是单纯的 workflow engine，也不只是一个 tool harness。
更准确地说，它处在三者交叉区：
- **最核心身份**：Claude Code / Codex 风格的本地 coding agent runtime
- **承载方式**：以 Python 实现的 agent loop + tool harness
- **扩展方式**：外挂了大量 runtime 子系统，例如 search、MCP、plan、task、team、workflow、worktree、plugin、hook policy
因此它不是一个“纯工作流系统”。workflow 在这里是一个被 agent 调用的能力域，而不是系统唯一中心。系统中心仍然是 `LocalCodingAgent` 的多轮模型-工具循环，见 `src/agent_runtime.py:103`、`src/agent_runtime.py:358`。
### 1.2 核心抽象是什么
这个项目有几个关键抽象：
- **Agent**：`LocalCodingAgent`，真正的 orchestrator，负责 prompt 构建、loop、工具调用、budget、session 持久化，见 `src/agent_runtime.py:103`
- **Session**：`AgentSessionState`，维护系统消息、用户上下文、assistant/tool transcript 以及 mutation lineage，见 `src/agent_session.py:89`
- **Tool**：`AgentTool` + `ToolExecutionContext`，以 OpenAI function calling 风格对工具进行 schema 化和执行，见 `src/agent_tools.py:44`、`src/agent_tools.py:73`
- **Prompt Context**：`PromptContext` / `AgentContextSnapshot`，把工作目录、git 状态、CLAUDE.md、各种 runtime 状态拼进模型上下文，见 `src/agent_prompting.py:15`、`src/agent_context.py:40`
- **StoredAgentSession`**：把完整 transcript、tool_calls、usage、file_history、plugin_state 持久化到 `.port_sessions/agent/*.json`，见 `src/session_store.py:53`
换句话说，它不是围绕“任务节点图”来设计的，而是围绕：
1. 当前 session 里有哪些上下文
2. 当前模型要不要发起 tool call
3. tool result 如何再次喂回模型
4. 何时 compact / stop / persist
### 1.3 与 Claude Code / Codex 的相似点与差异
#### 相似点
- 典型 **LLM-driven tool loop**：模型产出 tool call，runtime 执行工具，再把结果作为 `tool` message 回灌
- 以 **workspace / repository** 为中心，强依赖文件系统、git 状态、shell、搜索
- 支持 **系统提示词 + repo memory** 注入，尤其是 `CLAUDE.md`
- 有 **多轮对话 session**、resume、context compaction、权限 gating
- 支持 **Agent 子代理 / delegation**
#### 差异点
- 比 Claude Code / Codex 更“runtime platform 化”：这里塞了大量本地 runtime 子系统，如 `task_runtime`、`plan_runtime`、`team_runtime`、`workflow_runtime`、`remote_runtime`、`mcp_runtime`
- “skills” 实现较轻：当前更像 prompt-template / slash-command bridge，而不是成熟的按需 markdown 技能系统
- 权限模型相对简化：主要是 CLI 启动时布尔权限 + policy deny，而不是更细粒度的人机交互审批流
- 可观测性是“有 transcript / event / file_history 基础设施，但 UI 和诊断链条尚未完全产品化”
结论上，这个项目像是：
> 一个以 coding agent loop 为中心、向外扩张成通用本地 agent runtime 平台的 Python 实现。
---
## 2. Agent Loop
### 2.1 主循环入口
真实入口是 `LocalCodingAgent.run()`，它生成 `session_id`、scratchpad 目录，然后进入 `_run_prompt()`，见：
- `src/agent_runtime.py:358`
- `src/agent_runtime.py:413`
恢复会话则走 `resume()`，它把持久化 session 反序列化成 `AgentSessionState`，并补充 file history replay 与 compaction replay，见 `src/agent_runtime.py:376`。
### 2.2 每轮如何观察当前状态
Agent 的“观察”不是通过一个单独的 observe() 函数完成，而是在 loop 外预构建 session，并在每轮前做上下文压力处理：
1. **启动时构建 prompt context**
- `build_prompt_context()` -> `build_context_snapshot()`
- 汇总 cwd、platform、git status、scratchpad、CLAUDE.md bundle、各 runtime summary
- 见 `src/agent_runtime.py:240` 左右、`src/agent_prompting.py:30`、`src/agent_context.py:71`
2. **构建初始 session**
- `build_session()` 使用 system prompt parts + user_context/system_context 生成 session
- `AgentSessionState.create()` 会插入：
- `system` message
- `user_context reminder`
- 当前用户 prompt
- 见 `src/agent_runtime.py:255` 左右、`src/agent_session.py:97`
3. **每轮前的状态整理**
- `_microcompact_session_if_needed()`
- `_snip_session_if_needed()`
- `_compact_session_if_needed()`
- `_preflight_prompt_length()`
- 见 `src/agent_runtime.py:527-547`
因此，“观察当前状态”既包括文件系统 / git / runtime summary，也包括自身历史 transcript 的压缩后视图。
### 2.3 如何构造上下文
上下文构造分两层：
#### 第一层：环境与 memory 采样
`src/agent_context.py` 负责采样：
- cwd、shell、platform、date
- git status snapshot，见 `src/agent_context.py:279`
- scratchpad directory，见 `src/agent_context.py:197`
- `CLAUDE.md` / `.claude/CLAUDE.md` / `CLAUDE.local.md` / `.claude/rules/*.md` bundle，见 `src/agent_context.py:313-372`
- plugin / hook policy / MCP / remote / search / account / ask_user / config / LSP / plan / task / team / workflow / worktree 的 runtime summary，见 `src/agent_context.py:205-275`
#### 第二层：系统提示词装配
`build_system_prompt_parts()` 会拼接：
- system instructions
- doing tasks guidance
- tool usage guidance
- agent guidance
- plugin / MCP / search / account / ask-user / config / LSP / plan / task / team / hook policy guidance
- session-specific permission guidance
- simple env info
见 `src/agent_prompting.py:75-119`。
也就是说，这个项目的上下文不是“只把聊天记录喂给模型”，而是：
> transcript + injected local memory + runtime summaries + environment facts + permissions hints
### 2.4 如何决定下一步行动
行动选择主要由模型驱动。
每轮中 runtime 做的事情是：
1. 把 `session.to_openai_messages()` 和 `tool_specs` 发给模型，见 `src/agent_runtime.py:1153-1157`
2. 从返回中解析：
- 普通 assistant content
- tool calls
- finish_reason
- usage
3. 若无 tool call，则视作模型选择直接回答
4. 若有 tool call，则 runtime 执行这些工具，再把工具结果回灌到 session
真正的“决策”是模型自己通过 OpenAI tool calling 选择的，而不是 runtime 用规则树规划下一步。
因此 loop 属于：
- **外层固定流程**
- **内层模型驱动的动态行动选择**
### 2.5 如何调用工具
工具定义为 `AgentTool`，带：
- `name`
- `description`
- JSON Schema 参数定义 `parameters`
- `handler`
见 `src/agent_tools.py:73-111`。
每轮把所有工具变成 OpenAI function spec：
- `tool_specs = [tool.to_openai_tool() for tool in self.tool_registry.values()]`
- 见 `src/agent_runtime.py:463`
模型返回 tool call 后，主循环在 `src/agent_runtime.py:808-1119` 中执行：
- 创建一个 tool message 占位 `session.start_tool(...)`
- 记录 `tool_start` event
- 应用 plugin / hook policy preflight
- 执行 delegate / Skill / 普通 tool
- 以 `serialize_tool_result()` 将结果序列化成 JSON 字符串写回 transcript
### 2.6 工具结果如何回到模型上下文
工具结果通过 `session.finalize_tool(...)` 变成一个 `role='tool'` 的 message，内容是：
```json
{
"tool": "...",
"ok": true/false,
"content": "...",
"metadata": {...}
}
```
见：
- `src/agent_tools.py:1248`
- `src/agent_runtime.py:1037-1047`
下一轮模型调用时，`session.to_openai_messages()` 会把这些 tool messages 一并送回模型。因此工具结果不是旁路状态，而是标准 transcript 的一部分。
### 2.7 什么时候停止
停止条件有多类：
- **模型正常回答且无 tool_calls**：结束，见 `src/agent_runtime.py:764-806`
- **finish_reason = length/max_tokens**：自动注入 continuation prompt，再继续一轮，见 `src/agent_runtime.py:766-783`
- **budget exceeded**：停止，见 `src/agent_runtime.py:500-525`、`552-581`、`733-762`
- **prompt too long / preflight fail**：停止或先 compact 再试，见 `src/agent_runtime.py:543-605`
- **backend error**：停止，见 `src/agent_runtime.py:703-725`
- **达到 `max_turns`**：停止，见 `src/agent_runtime.py:1121-1146`
### 2.8 loop 是固定流程还是模型驱动
结论：
- **loop 骨架是固定的 runtime state machine**
- **每轮内的动作内容是模型驱动的**
固定部分是：
1. 整理上下文
2. 预算检查
3. 调模型
4. 若 tool_calls 则执行工具
5. 把工具结果写回 transcript
6. 进入下一轮或停止
动态部分是：
- 调什么工具
- 调多少个工具
- 是继续观察、修改还是直接回答
---
## 3. Context / Memory
### 3.1 是否有短期上下文
有。短期上下文就是当前 `AgentSessionState.messages`。
其中包含：
- system prompt
- user context reminder
- user / assistant / tool messages
- mutation metadata
见 `src/agent_session.py:89-148`。
### 3.2 是否有长期记忆
有，但不是向量数据库式长期记忆，而是 **文件化长期记忆**：
- `~/.claude/CLAUDE.md`
- 向上目录搜索的 `CLAUDE.md`
- `.claude/CLAUDE.md`
- `CLAUDE.local.md`
- `.claude/rules/*.md`
这些文件会在 session 创建时被 bundle 进 `user_context['claudeMd']`，见 `src/agent_context.py:205-207`、`313-372`。
因此它支持“repo memory / instruction memory”，但不支持自动写回、检索式 memory store 或 embedding memory。
### 3.3 是否有 conversation history
有，而且比较完整：
- 运行时 transcript：`AgentSessionState.messages`
- 持久化 transcript：`StoredAgentSession.messages`
- resume 后会恢复完整历史，见 `src/session_store.py:53-115`
工具调用、usage、message metadata 也一起保存。
### 3.4 是否有压缩 / summarize / compaction
有，而且这是一个比较成熟的部分。
机制分三层：
- **microcompact**：时间驱动的小型压缩，清理旧 tool results，见 `src/agent_runtime.py:113-115 import`、`src/agent_runtime.py:527-533`
- **snip**：把早期消息 tombstone 化为短摘要，见 `src/agent_runtime.py:533-537` 与 `_snip_session_pass`
- **compact**：调用 `compact_conversation()` 生成更正式的压缩摘要，见 `src/agent_runtime.py:538-547`、`src/agent_runtime.py:1240` 前后逻辑
此外还有：
- prompt too long 时的 **reactive compaction retry**
- resume 时的 **compaction replay**
见 `src/agent_runtime.py:3042-3142`。
### 3.5 是否有外部文件作为 memory
有，且非常明显：
- `CLAUDE.md` 系列
- `.claude/rules/*.md`
- 各类 workspace state 文件：config、plan、task、team、workflow、worktree 等 runtime manifest/state 文件
不过严格说，后者更多是 “runtime state injection”，不是纯 memory。
### 3.6 是否支持类似 CLAUDE.md / AGENTS.md / skills 的持久知识
#### CLAUDE.md
支持，且是当前唯一成熟的一类持久知识注入。
#### AGENTS.md
**不原生支持 `AGENTS.md` 作为 memory bundle**。当前 memory 发现逻辑只搜索 `CLAUDE.md`、`CLAUDE.local.md` 和 `.claude/rules/*.md`，见 `src/agent_context.py:355-372`。
#### skills
只支持“bundled skills”：
- 在 Python 代码里硬编码 skill 元数据和 prompt builder
- 通过 `Skill` 工具或 `/skills` 暴露
不支持从工作区扫描 markdown skill 文档并按需加载。
### 3.7 当前设计局限
1. **长期记忆是纯文件注入，不是检索式 memory**
- 规模大时容易塞满 prompt
- 没有 relevance ranking
2. **只识别 CLAUDE.md 家族，不识别 AGENTS.md**
- 对多代理协作约束不够统一
3. **resume 依赖 transcript replay，不是真正的 semantic memory**
- 历史很多时仍然会发生 compaction 丢失细节
4. **runtime summaries 很多，但上下文管理是“全量摘要注入”**
- 不是 query-time selective loading
5. **task / plan / workflow 已有，但未形成强约束的 workspace memory layout**
- 更像多个离散 runtime，而不是统一的 task-memory 文件系统
---
## 4. Tools / Actions
### 4.1 工具能力概览
核心工具能力包括：
- **文件系统**
- `list_dir`
- `read_file`
- `write_file`
- `edit_file`
- `notebook_edit`
- **搜索与代码理解**
- `glob_search`
- `grep_search`
- `LSP`
- `tool_search`
- **Shell**
- `bash`
- **Web / Search**
- `web_fetch`
- `web_search`
- search provider 管理工具
- **计划 / 任务**
- `update_plan`
- `plan_get`
- task runtime 相关工具
- **Human gate**
- `ask_user_question`
- **扩展 runtime**
- `mcp_*`
- `remote_*`
- `workflow_*`
- `worktree_*`
- `account_*`
- `config_*`
- **Agent 特有**
- `Agent` / `delegate_agent`
- `Skill`
tool registry 定义入口在 `src/agent_tools.py:210`。
### 4.2 工具 schema 怎么定义
每个工具是一个 `AgentTool`：
- `name`
- `description`
- `parameters`（JSON Schema）
- `handler`
见 `src/agent_tools.py:73-111`。
它通过 `to_openai_tool()` 转成 OpenAI-compatible function calling schema，见 `src/agent_tools.py:80-88`。
### 4.3 工具调用怎么执行
模型返回 tool call 后，runtime 会：
1. 解析 tool call，见 `src/openai_compat.py:273-298`
2. 在 loop 中逐个消费，见 `src/agent_runtime.py:808-1119`
3. 普通工具走 `execute_tool_streaming()` 或 `tool.execute()`，见 `src/agent_tools.py:181-207`
4. 特殊工具：
- `Agent` / `delegate_agent` 走子代理执行，见 `src/agent_runtime.py:2214`
- `Skill` 走 `_execute_skill()`，见 `src/agent_runtime.py:2059`
### 4.4 工具结果如何返回
工具结果统一封装为 `ToolExecutionResult`：
- `name`
- `ok`
- `content`
- `metadata`
然后 `serialize_tool_result()` 把它转成 JSON 字符串，塞入 tool message，见 `src/agent_tools.py:1248-1255`。
这意味着：
- 对模型来说，工具结果是 transcript 中的标准 `tool` message
- 对 runtime 来说，工具结果又带 `metadata`，可用于 file_history、policy event、plugin hook
### 4.5 是否有安全边界
有，但不是特别细粒度。
#### 文件边界
`_resolve_path()` 会强制路径位于 workspace root 内，防止越界，见 `src/agent_tools.py:1277-1288`。
#### 写权限边界
`write_file` / `edit_file` 受 `allow_file_write` 控制，见 `src/agent_tools.py:1291-1295`。
#### shell 权限边界
`bash` 受两层控制：
- `allow_shell_commands`
- `allow_destructive_shell_commands`
并有 destructive regex 阻断，比如 `rm`、`git reset --hard`、`git clean -fd` 等，见 `src/agent_tools.py:1298-1324`。
#### policy / hook deny
workspace 可以通过 `.claw-policy.json` / `.codex-policy.json` / `.claw-hooks.json` 配置 deny_tools、deny_tool_prefixes 以及 hook message，见 `src/hook_policy.py:160-256`。
#### CLI 层 deny context
还有一个更轻的 `ToolPermissionContext`，可按名字或前缀过滤工具，见 `src/permissions.py:7-17`。
### 4.6 这一层的架构评价
这个项目的 tools 层已经不是“几个本地 IO 工具”，而是：
> 一个围绕 workspace 资源、外部 runtime 状态和 agent orchestration 展开的统一 action surface。
优点是扩展性强，缺点是工具域越来越大后，模型对何时该用哪个工具会变得更依赖 prompt guidance。
---
## 5. Markdown / Workspace
### 5.1 是否支持 workspace-first
是，明显是 workspace-first 设计。
证据：
- `ToolExecutionContext.root` 是工作区根，见 `src/agent_tools.py:45`
- 所有文件工具都围绕 workspace root 做相对路径解析，见 `src/agent_tools.py:1277-1288`
- context 注入围绕 cwd、git repo、worktree、scratchpad、additional_working_directories 展开，见 `src/agent_context.py:71-99`
- 很多 runtime 都是 `from_workspace(cwd)` 初始化的
### 5.2 是否适合让 Agent 维护 `.md` 文件作为任务记忆
适合，而且比很多 agent 框架更适合。
原因：
- 已经原生支持 markdown 记忆文件注入（CLAUDE.md / rules）
- 文件读写/编辑能力完整
- 有 plan / task runtime，可作为结构化状态
- 有 scratchpad directory，可作为会话级临时区
不足是它没有约定一个统一的 task-memory 目录布局。
### 5.3 是否有任务目录 / workspace 概念
有 workspace 概念，但没有强约定的任务目录结构。
已有元素：
- workspace root
- additional working directories
- scratchpad root / scratchpad directory
- `.claude/` 作为本地 agent/runtime 元数据目录
但没有默认的：
- `/tasks/{task_id}/...`
- `/artifacts/...`
- `/memory/...`
### 5.4 能否改造成 task directory layout
完全可以，而且改造成本不高。
一个可行布局：
```text
/tasks/{task_id}/goal.md
/tasks/{task_id}/memory/open_questions.md
/tasks/{task_id}/memory/working_notes.md
/tasks/{task_id}/artifacts/report.md
/tasks/{task_id}/artifacts/commands.md
/tasks/{task_id}/artifacts/findings.md
```
最小改造方式：
1. 在 `task_runtime` 中给 task 增加 `task_root`
2. 在 `agent_context._load_memory_bundle()` 中把 `/tasks/{active_task}/memory/*.md` 纳入 memory discovery
3. 在 prompt context 中注入 `active task root`
4. 给 `update_plan` / task 工具增加 task-root 绑定
这样不需要重写 loop，只是增强 workspace memory layout。
---
## 6. Skills
### 6.1 当前是否支持 skill
支持，但属于 **弱 skill 系统**。
当前 skill 机制分两部分：
1. **Bundled skills**
- `BundledSkill` 定义 name / description / when_to_use / aliases / allowed_tools / get_prompt
- 见 `src/bundled_skills.py:22-32`
2. **Skill tool**
- `_execute_skill()` 优先查 bundled skill
- 查不到再退回 slash command
- 见 `src/agent_runtime.py:2059-2142`
### 6.2 是否有技能发现机制
有，但只对 bundled skill 生效：
- `format_skills_for_system_prompt()` 把 skill 列表渲染进系统提示，帮助模型“知道”有哪些 skill，见 `src/bundled_skills.py:268-289`
- GUI 也有 `/api/skills` 列表，见 `src/gui/server.py`
但它没有：
- 从工作区扫描 skill 文件
- 从 skill 文档按需加载正文
- skill-level semantic retrieval
### 6.3 是否支持 progressive disclosure
**严格说不支持。**
当前 bundled skill 更像：
- 用户 / 模型选中 skill
- skill 生成一段 prompt
- prompt 立即进入模型上下文
并不是：
- 先列 metadata
- 决定是否需要 skill
- 再按需读取 skill markdown 正文
- 只展开相关片段
因此它缺乏真正的 progressive disclosure。
### 6.4 如果没有，应该如何扩展
建议做一个最小可行版 workspace skill system，不破坏现有 loop。
#### 最小改造方案
##### 目录结构
```text
.claude/skills/
review/
skill.json
SKILL.md
data-agent/
skill.json
SKILL.md
python-debug/
skill.json
SKILL.md
```
##### metadata
`skill.json` 示例：
```json
{
"name": "data-agent",
"description": "Analyze datasets and produce structured markdown reports.",
"when_to_use": "When the task involves CSV/JSON/table exploration, metric comparison, or report writing.",
"aliases": ["data", "analysis"],
"allowed_tools": ["read_file", "write_file", "edit_file", "glob_search", "grep_search", "bash"],
"entry_markdown": "SKILL.md"
}
```
##### loading 时机
建议两阶段：
1. **session 初始化时只加载 metadata**
- 像 bundled skill 一样列进 system prompt
- 不把 `SKILL.md` 正文直接注入
2. **当模型选择 Skill 工具时再加载正文**
- `Skill(skill="data-agent")`
- runtime 读取对应 `SKILL.md`
- 返回 skill prompt 或 `<system-reminder>` 包装内容
##### Agent 如何决定读取哪个 skill
沿用现有机制，最小改造即可：
- 在 system prompt 里暴露 `name + description + when_to_use`
- 模型自己决定是否调用 `Skill`
- `Skill` 工具负责延迟读取 skill 正文
##### 代码落点
最小改造建议：
- 扩展 `src/bundled_skills.py` 为“bundled + discovered skills”
- 或新建 `workspace_skills.py`
- 在 `_execute_skill()` 中优先：
1. bundled skill
2. workspace discovered skill
3. slash command fallback
这个改法不会触碰 loop 主干，只是在 skill lookup 阶段增加一个来源。
---
## 7. Policy / Human Gate
### 7.1 如何处理权限
当前权限机制主要有三层。
#### 第一层：启动时权限布尔开关
`AgentPermissions`：
- `allow_file_write`
- `allow_shell_commands`
- `allow_destructive_shell_commands`
见 `src/agent_types.py:147-150`。
这是最直接的 runtime gate。
#### 第二层：workspace hook / policy
`HookPolicyRuntime` 支持：
- `trusted`
- `managed_settings`
- `safe_env_names`
- `deny_tools`
- `deny_tool_prefixes`
- `before_prompt`
- `after_turn`
- `before_tool`
- `after_tool`
- `budget_overrides`
见 `src/hook_policy.py:10-22`。
#### 第三层：ask_user runtime
并不是所有危险动作都会自动弹确认框。当前“人工确认”更像一个工具能力：
- `ask_user_question`
也就是说，模型可以选择向用户提问，但 runtime 本身不会像桌面 Codex 那样对每个危险动作自动出现审批 UI。
### 7.2 哪些动作会请求用户确认
严格来说，**默认没有统一的自动确认拦截器**。
当前模式更像：
- 文件写：如果没开 `allow_write`，直接拒绝
- shell：如果没开 `allow_shell`，直接拒绝
- destructive shell：如果没开 `--unsafe`，直接拒绝
- policy deny：直接拒绝
- ask-user：模型显式调用 `ask_user_question` 才会走人工澄清
因此它偏向：
> hard gate / deny-first，而不是 ask-on-demand 审批流。
### 7.3 哪些动作默认允许
默认允许的是安全读类能力，例如：
- read
- list
- search
- tool discovery
- runtime status inspection
默认不允许的是：
- 写文件
- shell
- destructive shell
具体提示也被写进 system prompt，见 `src/agent_prompting.py:388-401`。
### 7.4 是否有 deny / allow / ask 策略
有 `allow` 与 `deny`，但 `ask` 不是系统级统一策略。
- **allow**：CLI flag / runtime permissions
- **deny**：hook policy deny_tools / deny_tool_prefixes
- **ask**：只通过 `ask_user_question` 工具实现，非自动策略
### 7.5 是否支持项目级规则
支持。
项目级规则来自：
- `.claw-policy.json`
- `.codex-policy.json`
- `.claw-hooks.json`
并且会沿 cwd 向上目录发现，见 `src/hook_policy.py:160-187`。
### 7.6 对数据 Agent 的不足
如果你们要做数据 Agent，这套 human gate 还有几个明显缺口：
1. **缺少按数据源级别的权限模型**
- 没有“允许读 CSV 但不允许发网络请求”这种更细粒度策略
2. **没有结构化审批流**
- 例如“将执行 SQL / 访问线上表 / 导出结果集”的 ask approval 缺位
3. **没有数据脱敏/泄露策略**
- safe_env 只管环境变量，不管输出内容
4. **没有审计级 action classification**
- tool 结果有 metadata，但没有“高风险数据出站/高风险变更”的统一标签体系
5. **policy 更偏 workspace engineering，而不是 data governance**
如果面向数据 Agent，建议增加：
- data source allowlist
- query approval policy
- outbound redaction hook
- result size limits
- table/column sensitivity policy
---
## 8. Trace / Observability
### 8.1 是否记录每一轮模型输入输出
有记录，但“模型输入原文”不单独存为一条日志，而是可由 session transcript 和 system/user context 还原。
保存内容包括：
- `messages` transcript
- `system_prompt_parts`
- `user_context`
- `system_context`
- `usage`
- `turns`
- `tool_calls`
见 `src/session_store.py:53-115`、`src/agent_runtime.py:3269-3345`。
模型输出则直接进入 `assistant` messages。
### 8.2 是否记录工具调用
有，而且记录得比较细：
- transcript 中的 assistant tool_calls
- transcript 中的 tool result message
- `events` 中的 `tool_start` / `tool_delta` / `tool_result`
- `file_history` 中的摘要化变更记录
见 `src/agent_runtime.py:852-1119`。
### 8.3 是否记录文件变更
有，`file_history` 是一个重要机制。
resume 时会把 file_history replay 成一个 `<system-reminder>` 给模型，见：
- `src/agent_runtime.py:2914-3040`
持久化时也会一起保存到 session json，见：
- `src/session_store.py:66`
- `src/agent_runtime.py:3333`
它不是完整 patch log，但已经记录：
- action
- path / changed_paths
- snapshot ids
- before/after preview
- result preview
### 8.4 是否有 replay/debug 能力
有基础能力：
- `agent-resume`
- transcript 持久化
- file_history replay
- compaction replay
- GUI 可以展示 transcript 和 tool calls
但没有一个真正成熟的“调试控制台”或统一 trace viewer。
### 8.5 现有 observability 的优点
优点：
- 数据结构已经齐全：transcript、events、file_history、budget_state、plugin_state
- session 是 JSON 文件，易于离线分析
- message metadata 里保留了 mutation lineage / revision 信息
这意味着系统已经具备做更强 observability 的底座。
### 8.6 还缺什么
目前还缺：
1. **完整 prompt snapshot**
- 现在有 system/user context 和 transcript，但缺“每轮实际发给模型的最终 payload”落盘
2. **turn-level structured trace**
- 比如 `turn_03.json`
- 包含 prompt size、tool candidates、selected tool calls、latency、errors
3. **统一 replay viewer**
- 现在 resume 偏“继续工作”
- 不是“回放调试”
4. **tool latency / error taxonomy**
- 有 event，但缺统计聚合
5. **compaction provenance**
- 已有 replay，但缺图形化 lineage/summary mapping
### 8.7 如果要补，怎么加
最小建议：
#### 建议新增 trace 目录
```text
.port_sessions/traces/{session_id}/
turn_001.request.json
turn_001.response.json
turn_001.events.json
turn_001.tools.json
```
#### 每轮保存这些内容
- request
- rendered messages
- tool specs
- token budget snapshot
- response
- raw model response
- parsed tool calls
- finish_reason
- tools
- tool args
- tool result
- latency
- events
- 当前 turn 的 event list
#### 代码落点
最合适挂点在：
- `_query_model()` 前后
- tool loop `for tool_call in turn.tool_calls`
- `_persist_session()`
这样能复用现有 `session_id` 和 `turn_index`。
---
## 总结判断
这个项目已经具备一个完整 coding agent runtime 的主要骨架：
- 有明确的 session 与 transcript 模型
- 有模型驱动的动态工具循环
- 有 context injection 与 memory bundle
- 有 compaction / replay / resume
- 有较丰富的本地工具和 runtime 子系统
但从“下一代 workspace-native agent platform”的角度看，它还有几个明显缺口：
- skills 仍是 prompt-template 级，未形成 markdown-native progressive disclosure
- policy 偏 deny/allow，不是强审批流
- memory 已经文件化，但没有统一 task directory layout
- observability 有底座，缺一层真正可用的 trace 产品化视图
如果目标是把它改造成更强的“任务型数据 Agent / 文档驱动 Agent / workspace-memory-first Agent”，最值得优先补的不是 loop，而是三件事：
1. **workspace skill discovery + on-demand markdown loading**
2. **任务目录结构与 memory layout 约定**
3. **turn-level trace 持久化与 replay viewer**
这三项都可以在不重写 `LocalCodingAgent` 主循环的前提下增量演进。
README.md
+840 -752
View File
File diff suppressed because it is too large Load Diff
claw-code-agent.md
+845
View File
@@ -0,0 +1,845 @@
<p align="center">
<img src="images/logo.png" alt="Claw Code Agent logo" width="420" />
</p>
<h1 align="center">Claw Code Agent</h1>
<p align="center">
<em>A Python reimplementation of the Claude Code agent architecture — local models, full control, zero dependencies.</em>
</p>
<p align="center">
<a href="https://www.python.org/downloads/"><img src="https://img.shields.io/badge/python-3.10%2B-3776AB?logo=python&logoColor=white" alt="Python 3.10+"></a>
<a href="https://github.com/HarnessLab/claw-code-agent"><img src="https://img.shields.io/badge/repo-HarnessLab%2Fclaw--code--agent-181717?logo=github" alt="GitHub"></a>
<a href="https://docs.vllm.ai/"><img src="https://img.shields.io/badge/backend-vLLM-FF6F00?logo=lightning&logoColor=white" alt="vLLM"></a>
<a href="https://huggingface.co/Qwen/Qwen3-Coder-30B-A3B-Instruct"><img src="https://img.shields.io/badge/model-Qwen3--Coder-FFD21E?logo=huggingface&logoColor=black" alt="Qwen3-Coder"></a>
<img src="https://img.shields.io/badge/dependencies-zero-brightgreen" alt="Zero Dependencies">
<img src="https://img.shields.io/badge/status-alpha-orange" alt="Alpha">
<img src="https://img.shields.io/badge/license-open--source-green" alt="License">
</p>
---
## 📢 What's New
> **April 2026 — Major Update**
| | Feature | Details |
|---|---------|---------|
| 🆕 | **Interactive Chat Mode** | New `agent-chat` command — multi-turn REPL with `/exit` to quit |
| 🆕 | **Streaming Output** | Token-by-token streaming with `--stream` flag |
| 🆕 | **Plugin Runtime** | Full manifest-based plugin system — hooks, tool aliases, virtual tools, tool blocking |
| 🆕 | **Nested Agent Delegation** | Delegate subtasks to child agents with dependency-aware topological batching |
| 🆕 | **Agent Manager** | Lineage tracking, group membership, batch summaries for nested agents |
| 🆕 | **Custom Agent Profiles** | Discover local markdown-defined agents from `~/.claude/agents` and `./.claude/agents` and use them through the `Agent` tool |
| 🆕 | **Cost Tracking & Budgets** | Token budgets, cost budgets, tool-call limits, model-call limits, session-turn limits |
| 🆕 | **Structured Output** | JSON schema response mode with `--response-schema-file` |
| 🆕 | **Context Compaction** | Auto-snip, auto-compact, and reactive compaction on prompt-too-long errors |
| 🆕 | **File History Replay** | Journaling of file edits with snapshot IDs, replay summaries on session resume |
| 🆕 | **Truncation Continuation** | Automatic continuation when model response is cut off (`finish_reason=length`) |
| 🆕 | **Ollama Support** | Works out of the box with Ollama's OpenAI-compatible API |
| 🆕 | **LiteLLM Proxy Support** | Route through LiteLLM Proxy to any provider |
| 🆕 | **OpenRouter Support** | Cloud API gateway — access OpenAI, Anthropic, Google models via one endpoint |
| 🆕 | **Query Engine** | Runtime event counters, transcript summaries, orchestration reports |
| 🆕 | **Remote Runtime** | Manifest-backed local remote profiles, connect/disconnect state, and remote CLI/slash flows |
| 🆕 | **Hook & Policy Runtime** | Local `.claw-policy.json` / hook manifests with trust reporting, safe env, tool blocking, and budget overrides |
| 🆕 | **Task & Plan Runtime** | Persistent local tasks and plans with plan-to-task sync and dependency-aware task execution |
| 🆕 | **MCP Transport** | Real stdio MCP transport for `initialize`, resource listing/reading, and tool listing/calling |
| 🆕 | **Search Runtime** | Provider-backed `web_search` with local manifests, activation state, and `/search` flows |
| 🆕 | **Config & Account Runtime** | Local config/settings mutation plus manifest-backed account profiles and login/logout state |
| 🆕 | **Ask-User Runtime** | Queued or interactive local ask-user flow with history, slash commands, and agent tool support |
| 🆕 | **Team Runtime** | Persisted local teams and message history with team/message tools and slash/CLI inspection |
| 🆕 | **Notebook Edit Tool** | Native `.ipynb` cell editing through the real agent tool registry |
| 🆕 | **Workflow Runtime** | Manifest-backed local workflows with workflow tools, slash commands, and run history |
| 🆕 | **Remote Trigger Runtime** | Local remote triggers with create/update/run flows similar to the npm remote trigger surface |
| 🆕 | **Worktree Runtime** | Managed git worktrees with mid-session cwd switching, slash commands, and CLI flows |
| 🆕 | **Tokenizer-Aware Context** | Cached tokenizer backends with heuristic fallback for `/context`, `/status`, and compaction |
| 🆕 | **Prompt Budget Preflight** | Preflight prompt-length validation, token-budget reporting, and auto-compact/context collapse before backend failures |
| 🆕 | **LSP Runtime** | Local LSP-style code intelligence for definitions, references, hover, symbols, call hierarchy, and diagnostics |
| 🆕 | **Local Web GUI** | Browser-based chat UI via `python -m src.gui` — modern dark theme, slash command palette, session browser, settings panel |
| 🆕 | **Daemon Commands** | Local `daemon start/ps/logs/attach/kill` wrapper over background agent sessions |
| 🆕 | **Background Sessions** | Local `agent-bg`, `agent-ps`, `agent-logs`, `agent-attach`, and `agent-kill` flows |
| 🆕 | **Testing Guide** | Comprehensive [TESTING_GUIDE.md](TESTING_GUIDE.md) with commands for every feature |
| 🆕 | **Parity Checklist** | Full [PARITY_CHECKLIST.md](PARITY_CHECKLIST.md) tracking implementation status vs npm source |
---
## 📖 About
This repository reimplements the [Claude Code](https://docs.anthropic.com/en/docs/claude-code) npm agent architecture **entirely in Python**, designed to run with **local open-source models** via an OpenAI-compatible API server.
Built on the public porting workspace from [instructkr/claw-code](https://github.com/instructkr/claw-code), the active development lives at [HarnessLab/claw-code-agent](https://github.com/HarnessLab/claw-code-agent).
> **Goal:** Not to ship the original npm source, but to reimplement the full agent flow in Python — prompt assembly, context building, slash commands, tool calling, session persistence, and local model execution.
>
> **Zero external dependencies** — just Python's standard library.
<p align="center">
<img src="images/demo_2.gif" alt="Claw Code Agent demo" width="900" />
</p>
---
## ✨ Key Features
| Feature | Description |
|---------|-------------|
| 🤖 **Agent Loop** | Full agentic coding loop with tool calling and iterative reasoning |
| 💬 **Interactive Chat** | Multi-turn REPL via `agent-chat` with session continuity |
| 🖥️ **Local Web GUI** | Browser-based chat UI launched with `python -m src.gui` — sessions browser, slash command palette, live settings |
| 🧰 **Core Tools** | File read / write / edit, glob search, grep search, shell execution |
| 🔌 **Plugin Runtime** | Manifest-based plugins with hooks, aliases, virtual tools, and tool blocking |
| 🪆 **Nested Delegation** | Delegate subtasks to child agents with dependency-aware topological batching |
| 🧩 **Custom Agents** | Load local agent profiles from `~/.claude/agents` and `./.claude/agents`, inspect them via `/agents`, and delegate with `subagent_type` |
| 📡 **Streaming** | Token-by-token streaming output with `--stream` |
| 💬 **Slash Commands** | Local commands for context, config, account, search, MCP, remote, tasks, plan, hooks, and model control |
| 🌐 **Remote Runtime** | Manifest-backed remote profiles with local `remote-mode`, `ssh-mode`, `teleport-mode`, and connect/disconnect state |
| 🧭 **Task & Plan Runtime** | Persistent tasks and plans with sync, next-task selection, and blocked/unblocked state |
| 🛰️ **MCP Runtime** | Local MCP manifests plus real stdio MCP transport for resources and tools |
| 🔎 **Search Runtime** | Provider-backed `web_search` plus provider activation and status reporting |
| ⚙️ **Config & Account Runtime** | Local config mutation, settings inspection, account profiles, and login/logout state |
| 🙋 **Ask-User Runtime** | Queued answer or interactive user-question flow with history tracking |
| 👥 **Team Runtime** | Persisted local teams plus message history, handoff notes, and collaboration metadata |
| 📓 **Notebook Editing** | Native Jupyter notebook cell editing through `notebook_edit` |
| 🪵 **Worktree Runtime** | Managed git worktrees with `worktree_enter`, `worktree_exit`, and live cwd switching |
| 🧭 **Workflow Runtime** | Manifest-backed workflows with slash commands, CLI inspection, and recorded runs |
| ⏰ **Remote Triggers** | Local remote triggers with create/update/run flows and npm-style trigger actions |
| 🪝 **Hook & Policy Runtime** | Trust reporting, safe env, managed settings, tool blocking, and budget overrides |
| 🧠 **LSP Code Intelligence** | Local LSP-style definitions, references, hover, symbols, diagnostics, and call hierarchy |
| 🧠 **Context Engine** | Automatic context building with CLAUDE.md discovery, compaction, and snipping |
| 🔢 **Tokenizer-Aware Accounting** | Model-aware token counting with cached tokenizer backends and fallback heuristics |
| 📏 **Prompt Budgeting** | Soft/hard prompt-window checks, token-budget reports, and preflight context collapse |
| 🔄 **Session Persistence** | Save and resume agent sessions with file-history replay |
| 🗂️ **Background Sessions** | `agent-bg` and local daemon wrappers for background runs, logs, attach, and kill |
| 💰 **Cost & Budget Control** | Token budgets, cost limits, tool-call caps, model-call caps |
| 📋 **Structured Output** | JSON schema response mode for programmatic use |
| 🔐 **Permission System** | Granular control: `--allow-write`, `--allow-shell`, `--unsafe` |
| 🏗️ **OpenAI-Compatible** | Works with vLLM, Ollama, LiteLLM Proxy, OpenRouter — any OpenAI-compatible API |
| 🐉 **Qwen3-Coder** | First-class support for `Qwen3-Coder-30B-A3B-Instruct` via vLLM |
| 📦 **Zero Dependencies** | Pure Python standard library — nothing to install |
---
## 📋 Roadmap
### 📚 Documentation
| Document | Description |
|----------|-------------|
| [TESTING_GUIDE.md](TESTING_GUIDE.md) | Step-by-step commands to verify every feature |
| [PARITY_CHECKLIST.md](PARITY_CHECKLIST.md) | Full implementation status vs the npm source |
### ✅ Done
- [x] Python CLI agent loop
- [x] Interactive chat mode (`agent-chat`) with multi-turn REPL
- [x] OpenAI-compatible local model backend
- [x] Qwen3-Coder support through vLLM with `qwen3_xml` tool parser
- [x] Ollama, LiteLLM Proxy, and OpenRouter backends
- [x] Core tools: `list_dir`, `read_file`, `write_file`, `edit_file`, `glob_search`, `grep_search`, `bash`
- [x] Context building and `/context`-style usage reporting
- [x] Slash commands: `/help`, `/context`, `/context-raw`, `/token-budget`, `/prompt`, `/permissions`, `/model`, `/tools`, `/agents`, `/memory`, `/status`, `/clear`
- [x] Session persistence and `agent-resume` flow
- [x] Permission system (read-only, write, shell, unsafe tiers)
- [x] Streaming token-by-token assistant output
- [x] Truncated-response continuation flow
- [x] Auto-snip and auto-compact context reduction
- [x] Reactive compaction retry on prompt-too-long errors
- [x] Preflight prompt-length validation and token-budget reporting
- [x] Preflight auto-compact/context collapse before backend prompt-too-long failures
- [x] Cost tracking and usage budget enforcement
- [x] Token, tool-call, model-call, and session-turn budgets
- [x] Structured output / JSON schema response mode
- [x] File history journaling with snapshot IDs and replay summaries
- [x] Nested agent delegation with dependency-aware topological batching
- [x] Agent manager with lineage tracking and group membership
- [x] Filesystem-backed custom agent profiles with built-in/user/project precedence
- [x] Local custom-agent create/update/delete flows via CLI and `/agents`
- [x] Local daemon-style background command family
- [x] Local background session workflows: `agent-bg`, `agent-ps`, `agent-logs`, `agent-attach`, `agent-kill`
- [x] Local remote runtime: manifest discovery, profile listing, connect/disconnect persistence, and CLI/slash flows
- [x] Local hook and policy runtime with trust reporting, safe env, tool blocking, and budget overrides
- [x] Local config runtime: config discovery, effective settings, source inspection, and config mutation
- [x] Local LSP runtime: definitions, references, hover, symbols, diagnostics, and call hierarchy
- [x] Local account runtime: profile discovery, login/logout state, and account CLI/slash flows
- [x] Local ask-user runtime: queued answers, history, and ask-user CLI/slash flows
- [x] Local team runtime: persisted teams, team messages, and team CLI/slash flows
- [x] Local search runtime with provider discovery, activation, and provider-backed `web_search`
- [x] Local MCP runtime: manifest resources, stdio transport, MCP resources, and MCP tool calls
- [x] Local task and plan runtimes with plan sync and dependency-aware task execution
- [x] Notebook edit tool in the real Python tool registry
- [x] Local workflow runtime with workflow list/get/run tools and CLI/slash flows
- [x] Local remote trigger runtime with create/update/run flows and CLI/slash inspection
- [x] Local managed git worktree runtime with live cwd switching and worktree CLI/slash flows
- [x] Local web GUI (FastAPI + vanilla JS SPA) with chat, sessions browser, slash command palette, and live settings (`python -m src.gui`)
- [x] Tokenizer-aware context accounting with cached tokenizer backends and heuristic fallback
- [x] Plugin runtime: manifest discovery, hooks, aliases, virtual tools, tool blocking
- [x] Plugin lifecycle hooks: resume, persist, delegate phases
- [x] Plugin session-state persistence and resume restoration
- [x] Query engine facade driving the real Python runtime
- [x] Compaction metadata with lineage IDs and revision summaries
- [x] Extended runtime tools: `web_fetch`, `web_search`, `tool_search`, `sleep`
- [x] Unit tests for the Python runtime
- [x] `pyproject.toml` packaging with `setuptools`
### 🔲 In Progress
- [ ] Full MCP parity beyond the current stdio transport and local manifest/resource/tool support
- [ ] Full slash-command parity with npm runtime
- [ ] Full interactive REPL / TUI behavior
- [ ] Full tokenizer/chat-message framing parity beyond the current tokenizer-aware accounting
- [ ] Hooks system parity
- [ ] Real remote transport/runtime parity beyond the current local remote-profile runtime
- [ ] Voice and VIM modes
- [ ] Editor and platform integrations
- [ ] Background and team features
---
## 🏗️ Architecture
```text
claw-code/
├── README.md
├── TESTING_GUIDE.md # How to test every feature
├── PARITY_CHECKLIST.md # Implementation status vs npm source
├── pyproject.toml
├── .gitignore
├── images/
│ └── logo.png
├── src/ # Python implementation
│ ├── main.py # CLI entry point & argument parsing
│ ├── agent_runtime.py # Core agent loop (LocalCodingAgent)
│ ├── agent_tools.py # Tool definitions & execution engine
│ ├── agent_prompting.py # System prompt assembly
│ ├── agent_registry.py # Built-in + filesystem-backed custom agent discovery
│ ├── agent_context.py # Context building & CLAUDE.md discovery
│ ├── agent_context_usage.py # Context usage estimation & reporting
│ ├── agent_session.py # Session state management
│ ├── agent_slash_commands.py # Local slash command processing
│ ├── agent_manager.py # Nested agent lineage & group tracking
│ ├── agent_types.py # Shared dataclasses & type definitions
│ ├── openai_compat.py # OpenAI-compatible API client (streaming)
│ ├── plugin_runtime.py # Plugin manifest, hooks, aliases, virtual tools
│ ├── agent_plugin_cache.py # Plugin discovery & prompt injection cache
│ ├── session_store.py # Session serialization & persistence
│ ├── transcript.py # Transcript block export & mutation tracking
│ ├── query_engine.py # Query engine facade & runtime orchestration
│ ├── mcp_runtime.py # Local MCP discovery and stdio MCP transport
│ ├── search_runtime.py # Search providers and provider-backed web_search
│ ├── remote_runtime.py # Local remote profiles, connect/disconnect state, remote CLI support
│ ├── background_runtime.py # Local background sessions and daemon support
│ ├── account_runtime.py # Local account profiles, login/logout state, account CLI support
│ ├── ask_user_runtime.py # Local ask-user queued answers and interaction history
│ ├── config_runtime.py # Local workspace config/settings discovery and mutation
│ ├── lsp_runtime.py # Local LSP-style code intelligence and diagnostics
│ ├── token_budget.py # Prompt-window budgeting and preflight prompt-length validation
│ ├── plan_runtime.py # Persistent plan runtime and plan sync
│ ├── task_runtime.py # Persistent task runtime and task execution
│ ├── task.py # Task state model and task dataclasses
│ ├── team_runtime.py # Local teams, messages, and collaboration metadata
│ ├── workflow_runtime.py # Local workflow manifests and recorded workflow runs
│ ├── remote_trigger_runtime.py # Local remote trigger manifests and trigger run history
│ ├── worktree_runtime.py # Managed git worktree sessions and cwd switching
│ ├── hook_policy.py # Hook/policy manifests, trust, and safe env handling
│ ├── tokenizer_runtime.py # Tokenizer-aware context accounting backends
│ ├── permissions.py # Tool permission filtering
│ ├── cost_tracker.py # Cost & budget enforcement
│ ├── commands.py # Mirrored command inventory
│ ├── tools.py # Mirrored tool inventory
│ ├── runtime.py # Mirrored runtime facade
│ ├── reference_data/ # Mirrored inventory snapshots
│ └── gui/ # Local web GUI (FastAPI + vanilla JS SPA)
│ ├── __main__.py # `python -m src.gui` entry point
│ ├── server.py # FastAPI app and JSON endpoints
│ └── static/ # index.html, app.css, app.js
└── tests/ # Unit tests
├── test_agent_runtime.py
├── test_agent_context.py
├── test_agent_context_usage.py
├── test_agent_prompting.py
├── test_agent_slash_commands.py
├── test_main.py
├── test_query_engine_runtime.py
└── test_porting_workspace.py
```
---
## 📦 Requirements
| Requirement | Details |
|-------------|---------|
| 🐍 Python | `3.10` or higher |
| 📚 Dependencies | **None** — pure Python standard library |
| 🖥️ Model Server | `vLLM`, `Ollama`, `LiteLLM Proxy`, or `OpenRouter`, with tool calling support |
| 🧠 Model | [`Qwen/Qwen3-Coder-30B-A3B-Instruct`](https://huggingface.co/Qwen/Qwen3-Coder-30B-A3B-Instruct) (recommended) |
---
## 🚀 Quick Start
### 1. Start vLLM with Qwen3-Coder
vLLM must be started with automatic tool choice enabled. Use the `qwen3_xml` parser for Qwen3-Coder tool calling:
```bash
python -m vllm.entrypoints.openai.api_server \
--model Qwen/Qwen3-Coder-30B-A3B-Instruct \
--host 127.0.0.1 \
--port 8000 \
--enable-auto-tool-choice \
--tool-call-parser qwen3_xml
```
Verify the server is running:
```bash
curl http://127.0.0.1:8000/v1/models
```
> 📚 **References:** [vLLM Tool Calling Docs](https://docs.vllm.ai/en/v0.13.0/features/tool_calling/) · [OpenAI-Compatible Server](https://docs.vllm.ai/en/v0.13.0/serving/openai_compatible_server.html)
### Optional: Use Ollama Instead of vLLM
`claw-code-agent` can also work with Ollama because the runtime targets an OpenAI-compatible API. Use a model that supports tool calling well.
Example:
```bash
ollama serve
ollama pull qwen3
```
Then configure:
```bash
export OPENAI_BASE_URL=http://127.0.0.1:11434/v1
export OPENAI_API_KEY=ollama
export OPENAI_MODEL=qwen3
```
Notes:
- prefer tool-capable models such as `qwen3`
- plain chat-only models are not enough for full agent behavior
- Ollama does not use the `vLLM` parser flags shown above
> 📚 **References:** [Ollama OpenAI Compatibility](https://docs.ollama.com/api/openai-compatibility) · [Ollama Tool Calling](https://docs.ollama.com/capabilities/tool-calling)
### Optional: Use LiteLLM Proxy
`claw-code-agent` can also work through LiteLLM Proxy because the runtime targets an OpenAI-compatible chat completions API. The routed model still needs to support tool calling for full agent behavior.
Quick start example:
```bash
pip install 'litellm[proxy]'
litellm --model ollama/qwen3
```
LiteLLM Proxy runs on port `4000` by default. Then configure:
```bash
export OPENAI_BASE_URL=http://127.0.0.1:4000
export OPENAI_API_KEY=anything
export OPENAI_MODEL=ollama/qwen3
```
Notes:
- LiteLLM Proxy gives you an OpenAI-style gateway in front of many providers
- tool use still depends on the underlying routed model and provider behavior
- if you configure a LiteLLM master key, use that instead of `anything`
> 📚 **References:** [LiteLLM Docs](https://docs.litellm.ai/) · [LiteLLM Proxy Quick Start](https://docs.litellm.ai/)
### Optional: Use OpenRouter
`claw-code-agent` can also work with [OpenRouter](https://openrouter.ai/), a cloud API gateway that provides access to models from OpenAI, Anthropic, Google, Meta, and others through a single OpenAI-compatible endpoint. No local model server required.
Configure:
```bash
export OPENAI_BASE_URL=https://openrouter.ai/api/v1
export OPENAI_API_KEY=sk-or-v1-your-key-here
export OPENAI_MODEL=openai/gpt-4o-mini
```
Notes:
- sign up at [openrouter.ai](https://openrouter.ai/) and create an API key under [Keys](https://openrouter.ai/keys)
- model names use the `provider/model` format (e.g. `anthropic/claude-sonnet-4`, `openai/gpt-4o`, `google/gemini-2.5-pro`)
- tool calling support varies by model — check the [model list](https://openrouter.ai/models) for capabilities
- this sends your conversation (including file contents and shell output) to OpenRouter and the upstream provider — do not use with repos containing secrets or sensitive data
> 📚 **References:** [OpenRouter Docs](https://openrouter.ai/docs) · [Supported Models](https://openrouter.ai/models) · [API Keys](https://openrouter.ai/keys)
### 2. Configure Environment
```bash
export OPENAI_BASE_URL=http://127.0.0.1:8000/v1
export OPENAI_API_KEY=local-token
export OPENAI_MODEL=Qwen/Qwen3-Coder-30B-A3B-Instruct
```
### Use Another Model With vLLM
If you want to try another model, keep the same `vLLM` server setup and change the `--model` value when you launch `vLLM`.
Example:
```bash
python -m vllm.entrypoints.openai.api_server \
--model your-model-name \
--host 127.0.0.1 \
--port 8000 \
--enable-auto-tool-choice \
--tool-call-parser your_parser
```
Then update:
```bash
export OPENAI_MODEL=your-model-name
```
Notes:
- the documented path in this repository is `vLLM`
- the model must support tool calling well enough for agent use
- some model families require a different `--tool-call-parser`
- slash commands such as `/help`, `/context`, and `/tools` are local and do not require the model server
### 3. Run the Agent
```bash
# Read-only question
python3 -m src.main agent \
"Read src/agent_runtime.py and summarize how the loop works." \
--cwd .
# Write-enabled task
python3 -m src.main agent \
"Create TEST_QWEN_AGENT.md with one line: test ok" \
--cwd . --allow-write
# Shell-enabled task
python3 -m src.main agent \
"Run pwd and ls src, then summarize the result." \
--cwd . --allow-shell
# Interactive chat mode
python3 -m src.main agent-chat --cwd .
# Streaming output
python3 -m src.main agent \
"Explain the current architecture." \
--cwd . --stream
```
---
## 🛠️ Usage
### Agent Commands
| Command | Description |
|---------|-------------|
| `agent <prompt>` | Run the agent with a prompt |
| `agent-chat [prompt]` | Start interactive multi-turn chat mode |
| `agent-bg <prompt>` | Run the agent in a local background session |
| `agent-ps` | List local background sessions |
| `agent-logs <id>` | Show background session logs |
| `agent-attach <id>` | Show the current background output snapshot |
| `agent-kill <id>` | Stop a background session |
| `daemon <subcommand>` | Daemon-style wrapper over local background sessions |
| `agent-prompt` | Show the assembled system prompt |
| `agent-context` | Show estimated context usage |
| `agent-context-raw` | Show the raw context snapshot |
| `token-budget` | Show prompt-window budget, reserves, and soft/hard input limits |
| `agents [agent_type]` | List active local agent definitions or show one agent profile |
| `agents-create <agent_type>` | Create a project or user agent definition markdown file |
| `agents-update <agent_type>` | Update an existing project or user agent definition |
| `agents-delete <agent_type>` | Delete an existing project or user agent definition |
| `agent-resume <id> <prompt>` | Resume a saved session |
### Runtime Utility Commands
| Command | Description |
|---------|-------------|
| `search-status` / `search-providers` / `search-activate` / `search` | Inspect and use the local search runtime |
| `mcp-status` / `mcp-resources` / `mcp-resource` / `mcp-tools` / `mcp-call-tool` | Inspect and use the local MCP runtime |
| `remote-status` / `remote-profiles` / `remote-disconnect` | Inspect local remote runtime state |
| `remote-mode` / `ssh-mode` / `teleport-mode` / `direct-connect-mode` / `deep-link-mode` | Activate local remote runtime modes |
| `config-status` / `config-effective` / `config-source` / `config-get` / `config-set` | Inspect and mutate local config/settings |
| `account-status` / `account-profiles` / `account-login` / `account-logout` | Inspect and mutate local account state |
### CLI Flags
| Flag | Description |
|------|-------------|
| `--cwd <path>` | Set the workspace directory |
| `--model <name>` | Override the model name |
| `--base-url <url>` | Override the API base URL |
| `--allow-write` | Allow the agent to modify files |
| `--allow-shell` | Allow the agent to execute shell commands |
| `--unsafe` | Allow destructive shell operations |
| `--stream` | Enable token-by-token streaming output |
| `--show-transcript` | Print the full message transcript |
| `--scratchpad-root <path>` | Override the scratchpad directory |
| `--system-prompt <text>` | Set a custom system prompt |
| `--append-system-prompt <text>` | Append to the system prompt |
| `--override-system-prompt <text>` | Replace the generated system prompt |
| `--add-dir <path>` | Add extra directories to context |
### Budget & Limit Flags
| Flag | Description |
|------|-------------|
| `--max-total-tokens <n>` | Total token budget |
| `--max-input-tokens <n>` | Input token budget |
| `--max-output-tokens <n>` | Output token budget |
| `--max-reasoning-tokens <n>` | Reasoning token budget |
| `--max-budget-usd <n>` | Maximum cost in USD |
| `--max-tool-calls <n>` | Maximum tool calls per run |
| `--max-delegated-tasks <n>` | Maximum delegated subtasks |
| `--max-model-calls <n>` | Maximum model API calls |
| `--max-session-turns <n>` | Maximum session turns |
| `--input-cost-per-million <n>` | Input token pricing |
| `--output-cost-per-million <n>` | Output token pricing |
### Context Control Flags
| Flag | Description |
|------|-------------|
| `--auto-snip-threshold <n>` | Auto-snip older messages at this token count |
| `--auto-compact-threshold <n>` | Auto-compact at this token count |
| `--compact-preserve-messages <n>` | Messages to preserve during compaction |
| `--disable-claude-md` | Disable CLAUDE.md discovery |
### Structured Output Flags
| Flag | Description |
|------|-------------|
| `--response-schema-file <path>` | JSON schema file for structured output |
| `--response-schema-name <name>` | Schema name identifier |
| `--response-schema-strict` | Enforce strict schema validation |
### Slash Commands
These are handled **locally** before the model loop:
| Command | Aliases | Description |
|---------|---------|-------------|
| `/help` | `/commands` | Show built-in slash commands |
| `/context` | `/usage` | Show estimated session context usage |
| `/context-raw` | `/env` | Show raw environment & context snapshot |
| `/token-budget` | `/budget` | Show prompt-window budget, reserves, and soft/hard input limits |
| `/mcp` | — | Show MCP runtime status, tools, or a single MCP tool |
| `/resources` | — | List MCP resources |
| `/resource` | — | Read an MCP resource by URI |
| `/search` | — | Show search status, providers, activate a provider, or run a search |
| `/remote` | — | Show local remote status or activate a target |
| `/remotes` | — | List local remote profiles |
| `/ssh` | — | Activate an SSH-style remote profile |
| `/teleport` | — | Activate a teleport-style remote profile |
| `/direct-connect` | — | Activate a direct-connect remote profile |
| `/deep-link` | — | Activate a deep-link remote profile |
| `/disconnect` | `/remote-disconnect` | Disconnect the active remote runtime target |
| `/account` | — | Show account runtime status or profiles |
| `/login` | — | Activate a local account profile or identity |
| `/logout` | — | Clear the active account session |
| `/config` | `/settings` | Inspect effective config, sources, or a single config value |
| `/plan` | `/planner` | Show the local plan runtime state |
| `/tasks` | `/todo` | Show the local task list |
| `/task` | — | Show a task by id |
| `/task-next` | `/next-task` | Show the next actionable tasks |
| `/prompt` | `/system-prompt` | Render the effective system prompt |
| `/hooks` | `/policy` | Show local hook/policy manifests |
| `/trust` | — | Show trust mode, managed settings, and safe env values |
| `/permissions` | — | Show active tool permission mode |
| `/model` | — | Show or update the active model |
| `/tools` | — | List registered tools with permission status |
| `/agents` | — | List, show, create, update, or delete local agent definitions |
| `/memory` | — | Show loaded CLAUDE.md memory bundle |
| `/status` | `/session` | Show runtime/session status summary |
| `/clear` | — | Clear ephemeral runtime state |
```bash
python3 -m src.main agent "/help"
python3 -m src.main agent "/context" --cwd .
python3 -m src.main agent "/token-budget" --cwd .
python3 -m src.main agent "/tools" --cwd .
python3 -m src.main agent "/agents" --cwd .
python3 -m src.main agent "/status" --cwd .
```
### Custom Agent Definitions
Custom agent profiles can live in either of these directories:
- `./.claude/agents/*.md`
- `~/.claude/agents/*.md`
Project agents override user agents, and user agents override built-ins when the `agent_type` matches.
Example agent file:
```md
---
name: reviewer
description: "Review implementation changes carefully."
tools: read_file, grep_search
model: Qwen/Qwen3-Coder-30B-A3B-Instruct
initialPrompt: Start by identifying the highest-risk files.
---
Inspect code changes and summarize correctness risks, regressions, and missing tests.
```
Inspect the loaded profiles:
```bash
python3 -m src.main agents --cwd .
python3 -m src.main agents reviewer --cwd .
python3 -m src.main agent "/agents" --cwd .
python3 -m src.main agent "/agents show reviewer" --cwd .
```
Create, update, or delete agent files from the CLI:
```bash
python3 -m src.main agents-create reviewer \
--cwd . \
--description "Review implementation changes carefully." \
--prompt "Inspect code changes and summarize risks." \
--tools read_file,grep_search \
--model Qwen/Qwen3-Coder-30B-A3B-Instruct
python3 -m src.main agents-update reviewer \
--cwd . \
--description "Review implementation changes and tests carefully." \
--prompt "Focus on regressions, missing tests, and risky diffs."
python3 -m src.main agents-delete reviewer --cwd . --source project
```
Or use the local slash command management forms:
```bash
python3 -m src.main agent "/agents create reviewer :: Review implementation changes carefully. :: Inspect code changes and summarize risks." --cwd .
python3 -m src.main agent "/agents update reviewer Updated review description :: Focus on regressions and missing tests." --cwd .
python3 -m src.main agent "/agents delete reviewer" --cwd .
```
### Utility Commands
```bash
python3 -m src.main summary # Workspace summary
python3 -m src.main manifest # Workspace manifest
python3 -m src.main commands --limit 10 # Command inventory
python3 -m src.main tools --limit 10 # Tool inventory
```
---
## 🔧 Built-in Tools
The runtime currently includes core and extended tools:
| Tool | Description | Permission |
|------|-------------|------------|
| `list_dir` | List files and directories | 🟢 Always |
| `read_file` | Read file contents (with line ranges) | 🟢 Always |
| `write_file` | Write or create files | 🟡 `--allow-write` |
| `edit_file` | Edit files via exact string matching | 🟡 `--allow-write` |
| `glob_search` | Find files by glob pattern | 🟢 Always |
| `grep_search` | Search file contents by regex | 🟢 Always |
| `bash` | Execute shell commands | 🔴 `--allow-shell` |
| `web_fetch` | Fetch local or remote text content by URL | 🟢 Always |
| `search_status` / `search_list_providers` / `search_activate_provider` / `web_search` | Search runtime status and provider-backed web search | 🟢 Always |
| `tool_search` | Search the current Python tool registry | 🟢 Always |
| `sleep` | Bounded local wait tool | 🟢 Always |
| `config_list` / `config_get` / `config_set` | Inspect and mutate local workspace config | `config_set` is 🟡 `--allow-write` |
| `account_status` / `account_list_profiles` / `account_login` / `account_logout` | Inspect and mutate local account state | 🟢 Always |
| `remote_status` / `remote_list_profiles` / `remote_connect` / `remote_disconnect` | Inspect and mutate local remote runtime state | 🟢 Always |
| `mcp_list_resources` / `mcp_read_resource` / `mcp_list_tools` / `mcp_call_tool` | Use local MCP resources and transport-backed MCP tools | 🟢 Always |
| `plan_get` / `update_plan` / `plan_clear` | Inspect and mutate the local plan runtime | `update_plan` is 🟡 `--allow-write` |
| `task_next` / `task_list` / `task_get` / `task_create` / `task_update` / `task_start` / `task_complete` / `task_block` / `task_cancel` / `todo_write` | Persistent local task and todo management | write-like task mutations are 🟡 `--allow-write` |
| `delegate_agent` | Delegate work to nested child agents | 🟢 Always |
---
## 🔌 Plugin System
Claw Code Agent supports a **manifest-based plugin runtime**. Drop a `plugin.json` in a `plugins/` subdirectory:
```json
{
"name": "my-plugin",
"hooks": {
"beforePrompt": "Inject guidance into the system prompt.",
"afterTurn": "Run after each agent turn.",
"onResume": "Reapply state on session resume.",
"beforePersist": "Save state before session is saved.",
"beforeDelegate": "Inject guidance before child agents.",
"afterDelegate": "Process child agent results."
},
"toolAliases": [
{ "name": "my_read", "baseTool": "read_file", "description": "Custom read alias." }
],
"virtualTools": [
{ "name": "my_tool", "description": "A virtual tool.", "responseTemplate": "result: {input}" }
]
}
```
> See [TESTING_GUIDE.md](TESTING_GUIDE.md) **Section 19** for full plugin testing commands.
---
## 🪆 Nested Agent Delegation
The agent can delegate subtasks to child agents with full context carryover:
```bash
python3 -m src.main agent \
"Delegate a subtask to inspect src/agent_runtime.py and return a summary." \
--cwd . --show-transcript
```
Features:
- Sequential and parallel subtask execution
- Dependency-aware topological batching
- Child-session save and resume
- Agent manager lineage tracking
> See [TESTING_GUIDE.md](TESTING_GUIDE.md) **Section 20** for delegation testing commands.
---
## 🖥️ Local Web GUI
If the terminal isn't your thing, launch the bundled browser GUI:
```bash
python3 -m src.gui --cwd . --allow-write --allow-shell
```
Your default browser opens to `http://127.0.0.1:8765` with a modern dark-themed chat UI.
| Flag | Description |
|------|-------------|
| `--host <addr>` | Bind address (default `127.0.0.1`) |
| `--port <n>` | Port to listen on (default `8765`) |
| `--cwd <path>` | Workspace directory the agent operates in |
| `--model <name>` | Override the model name |
| `--base-url <url>` | Override the OpenAI-compatible API base URL |
| `--api-key <key>` | API key for the model server |
| `--session-dir <path>` | Where saved sessions live |
| `--allow-write` | Allow file write/edit tools |
| `--allow-shell` | Allow shell execution |
| `--no-browser` | Don't auto-open a browser tab |
The GUI surfaces:
- multi-turn chat with tool-call cards (collapsible JSON args + results)
- saved sessions sidebar with one-click resume
- slash command and skill pickers (`/` and `★` buttons, or `Cmd/Ctrl+K`)
- live settings panel (model, base URL, working dir, permissions)
- usage / cost meta in the composer footer
> **Note:** The GUI uses [FastAPI](https://fastapi.tiangolo.com/) and [Uvicorn](https://www.uvicorn.org/) under the hood. These get installed automatically if you install the package via `pip install -e .`. The core Python agent runtime itself remains dependency-free.
---
## 🔄 Session Persistence
Each `agent` run automatically saves a resumable session:
```text
session_id=4f2c8c6f9c0e4d7c9c7b1b2a3d4e5f67
session_path=.port_sessions/agent/4f2c8c6f...
```
Resume a previous session:
```bash
python3 -m src.main agent-resume \
4f2c8c6f9c0e4d7c9c7b1b2a3d4e5f67 \
"Continue the previous task and finish the missing parts."
```
Resume directly into interactive chat:
```bash
python3 -m src.main agent-chat \
--resume-session-id <session-id> \
--cwd .
```
Inspect saved sessions:
```bash
ls -lt .port_sessions/agent
```
> **Note:** Run `agent-resume` from the same `claw-code/` directory where the session was created. A resumed session continues from the saved transcript, not from scratch.
---
## 🧪 Testing
Run the full test suite:
```bash
python3 -m unittest discover -s tests -v
```
Smoke tests:
```bash
python3 -m src.main agent "/help"
python3 -m src.main agent-context --cwd .
python3 -m src.main agent \
"Read src/agent_session.py and summarize the message flow." \
--cwd .
```
> 📚 **Full testing guide:** See [TESTING_GUIDE.md](TESTING_GUIDE.md) for step-by-step commands covering the full implemented runtime surface.
---
## 🔐 Permission Model
Claw Code Agent uses a **tiered permission system** to keep the agent safe by default:
| Tier | Capability | Flag Required |
|------|-----------|---------------|
| **Read-only** | List, read, glob, grep | None (default) |
| **Write** | + file creation and editing | `--allow-write` |
| **Shell** | + shell command execution | `--allow-shell` |
| **Unsafe** | + destructive shell operations | `--unsafe` |
---
## 🔎 Parity Status
The full implementation checklist tracking parity against the npm `src` lives in [PARITY_CHECKLIST.md](PARITY_CHECKLIST.md).
It covers: core runtime, CLI modes, prompt assembly, context/memory, slash commands, tools, permissions, plugins, MCP, REPL/TUI, remote features, editor integrations, and internal subsystems.
---
## ⚠️ Disclaimer
- This repository is a **Python reimplementation** inspired by the Claude Code npm architecture.
- It does **not** ship the original npm source.
- It is **not** affiliated with or endorsed by Anthropic.
---
<p align="center">
<sub>Built with 🐍 Python · Powered by 🐉 HarnessLab Team.</sub>
</p>
data_agent_v0.md
+206 -368
View File
@@ -1,149 +1,29 @@
文档结构
1. 数据迭代Agent架构
- 1-2周MVP方案
- badcase反馈渠道接入、自动收集分析
- 1-2周MVP方案
1. 定义一个最小的任务流程，整理流程中AI需要具备的能力
- 工具
- 记忆
- 环境
- 技术选型
中控数据Agent构建-汇报
Badcase 反馈渠道接入与自动收集分析:数据挖掘Agent设计方案
Router Data Agent Workbench 方案文档
1. 背景
当前快慢系统路由的数据开发流程，主要围绕以下任务展开：
- 分析需求 / badcase
- 明确快慢系统边界
- 构建评测集
- 构建训练集
- 挖掘线上样本
- 人工标注与复核
- 模型训练与回放评估
- 根据结果继续补齐数据
现有流程本质上仍然是 人驱动的数据开发
人理解需求
→ 人拆解边界
→ 人写 prompt / 规则
→ 人捞数据
→ 人筛样本
→ 人整理评测集
→ 人分析模型问题
→ 人沉淀经验
这个流程可以用 AI 做局部提效，但如果只是把每一步变成一个 LLM 节点，本质上仍然是旧框架。
本项目希望重构的不是某几个节点，而是整个数据开发范式。
---
1.1 业务尝试：快慢系统评测集构建
当前路由标签空间包括：
FAST_DIRECT
SLOW_FILTER_RANK
SLOW_DISAMBIGUATE
SLOW_GOAL_STATE
SLOW_WORKFLOW
SLOW_CONTEXT_DEPENDENT
SLOW_UNCLEAR
SLOW_ADVANCED_CAPABILITY
这些标签不是普通分类标签，而是路由系统的 能力边界定义。
评测集构建的核心目标也不是简单判断 fast / slow，而是判断：
这个请求为什么复杂？
complexity reason 是什么？
例如：
导航到附近停车场
→ FAST_DIRECT
导航到附近最大的停车场
→ SLOW_FILTER_RANK
真正困难的不是打标签本身，而是持续维护这些边界：
- 哪些请求快系统可以稳定承接？
- 哪些请求必须交给慢系统？
- 哪些 case 是边界混淆？
- 哪些标签定义不清？
- 哪些线上 badcase 暴露了新的边界问题？
- 哪些模型错误值得转成训练集 / 评测集？
2. 数据迭代Agent架构
建设一个面向快慢路由系统的数据开发 Agent 环境：Router Data Agent Workbench
它的目标是：
让 Agent 能够围绕一个需求 / badcase，自主理解问题、探索数据、发现边界冲突、提出人工裁决问题、生成评测集候选、沉淀长期经验，从而显著提升路由评测 / 训练数据构建效率。
目标不是做一个固定流程平台，而是做一个 Agent-native 的数据开发工作台。
---
2.1 Agent定位
- 不做传统 workflow+LLM节点提效
1. 背景与目标
- 数据开发是中控核心工作之一，但当前流程仍以人工驱动为主。
- 需求 / badcase 驱动的评测集构建、样本补充和线上挖掘链路分散，人工介入重、复用性差。
- 结合近期 AI native 工作方式转变，我们希望基于 Agent 底座先打通最小数据开发闭环。
当前方式的瓶颈与挑战：
- 人工驱动重：从需求、badcase 到评测集构建，多个关键环节依赖人工推进。
- 流程割裂重：人工构造、线上挖掘、LLM 生成彼此分散，数据格式转换和整理成本高。
- 经验复用弱：边界判断和处理经验难以沉淀，导致新问题进入后仍需重复劳动。
数据开发范式转变：
[图片]
2.1.1 不做传统 workflow
不采用这种模式：
需求理解节点
→ 边界分析节点
→ 样本挖掘节点
→ 预打标节点
→ 人工审核节点
→ 评测集生成节点
这种方式的问题是：
- 还是人预先设计流程
- LLM 只是填充节点
- Agent 没有真正自主决策
- 新问题仍然需要人调整流程 / prompt
- 长期价值有限
这不是 AI 原生，而是旧流程自动化。
2. AI Native数据Agent
不是做一个固定流程平台，而是做一个 Agent-native 的数据开发工作台。
让 Agent 能够围绕一个需求 / badcase，自主理解问题、探索数据、发现边界冲突、提出人工裁决问题、生成评测集候选、沉淀长期经验，从而显著提升路由评测 / 训练数据构建效率。
---
2.1.2 做 Agent-native workbench
目标模式是：
给 Agent 一个目标、工作区、资料、工具、经验、权限和评价标准；
Agent 自己决定下一步做什么；
系统负责提供环境、边界、记录、校验和人工裁决入口。
核心区别：
传统 Workflow
Agent-native Workbench
人提前画流程
Agent 根据任务自主推进
LLM 填节点
Agent 自己选择资料、工具和行动
prompt 是核心
workspace / skills / memory / tools 是核心
人负责执行大量步骤
人只负责关键业务裁决
每次任务从头开始
经验持续沉淀，下一次复用
输出一个结果
输出结果 + 过程 + 经验 + 可复用资产
2.1 设计目标与边界
- 核心目标：基于一个精简、可定制的 Agent 底座，建设一个面向中控数据开发场景的智能体执行底座。
- 方案形态：不是“流程自动化 + LLM 节点”，而是一个以 Agent 为核心、能够围绕任务自主检索、生成、筛选和整理的数据开发执行底座。
- 实现方式：基于 code-agent / claw-code-agent 实现，复用 Agent loop、文件读写、工具调用、代码执行、过程记录等通用能力。
[图片]
---
2.2 系统定位
Router Data Agent Workbench 应该承担以下职责：
输入：
- 需求文档
- badcase
- 线上 session
- 当前标签定义
- 历史评测集
- 模型预测结果
- 人工裁决记录
输出：
- 边界分析
- open questions
- 人工裁决问题
- 候选样本池
- 标注任务
- 专项评测集候选
- 训练集候选
- 回放评估报告
- 标签定义修订建议
- 可复用经验
它不是一个“评测集生成器”，而是一个 路由数据开发 Agent 工作环境。
---
2.3 核心架构
Router Data Agent Workbench 由 6 个核心要素组成：
2.2 核心架构
- 中控数据Agent应该由 6 个核心要素组成：
- Workspace：任务工作区
- Skills：领域经验包
- Tools：可执行工具
@@ -152,7 +32,7 @@ Router Data Agent Workbench 由 6 个核心要素组成：
[图片]
---
2.4 Workspace：任务工作区
2.2.1 Workspace：任务工作区
每个需求 / badcase 启动后，系统创建一个独立 workspace。
示例结构：
[图片]
@@ -163,32 +43,14 @@ Workspace 的作用：
- 支持人机协作
- 沉淀可复用经验
- 保证过程可追溯
Agent 不是在一个固定流程里跑，而是在 workspace 中像研究员一样工作。
Agent 不是在一个固定流程里跑，而是在 workspace 按照我们之前的工作流程去工作
---
2.5 MD First：以 Markdown 作为 Agent 工作语言
2.2.2 MD First：以 Markdown 作为 Agent 工作语言
[图片]
Agent 工作过程优先使用 Markdown
适合用 Markdown 的内容：
需求理解
边界分析
open questions
人工裁决记录
挖掘策略
失败尝试
经验总结
效果报告
标签定义说明
原因：
- MD 更适合人读
- MD 更适合 Agent 自然读写
- MD 更适合沉淀讨论和判断过程
- MD 更接近真实工作台，而不是状态机
但不是完全不要结构化。
原则是：
MD 是 Agent 的工作语言；
JSONL / CSV / DB 是数据资产的交换格式。
也就是：
- MD 是 Agent 的工作语言；
- JSONL / CSV / DB 是数据资产的交换格式。
内容
推荐格式
需求理解
@@ -209,22 +71,10 @@ JSONL
表格 + MD 报告
工具调用参数
schema / JSON
最终原则：
Agent 工作过程 MD first；
系统边界 schema when needed。
---
2.6 Skills：领域经验包，而不是流程节点
2.2.3 Skills：固化成熟工作流程
[图片]
Skills 不应该被设计成固定节点。
错误理解：
Skill 1：需求理解
Skill 2：边界分析
Skill 3：数据挖掘
Skill 4：预打标
Skill 5：评测生成
这还是 workflow。
正确理解：
Skill 是 Agent 可发现、可按需加载、可组合的领域经验包。
示例：
/skills/
@@ -261,33 +111,10 @@ Agent 在运行中根据问题自主选择是否读取某个 skill。
发现模型离线准确率高但线上效果差
→ 读取 active-learning-router skill
Skill 的价值不是定义流程，而是沉淀经验。
Skill ：之前工作经验的沉淀
---
2.7 Resources：可检索资料
Resources 是 Agent 可读取的业务上下文。
包括：
当前标签定义
历史标签定义版本
历史 badcase
历史人工裁决
已有评测集
已有训练集
线上 session 索引
topquery 集合
模型预测结果
模型误判样本
历史回放报告
Agent 不应该一次性把所有资料塞进上下文。
更合理的方式是：
Agent 先读任务目标
→ 判断需要什么资料
→ 按需检索相关资源
→ 只把当前需要的内容纳入上下文
这样可以避免上下文污染，也能让 Agent 更像真实研究员一样探索。
---
2.8 Tools：可执行能力
2.2.4 Tools：可执行能力
Tools 是 Agent 可以调用的实际能力。
示例：
search_online_sessions()
@@ -314,7 +141,7 @@ Agent 自己决定：
什么时候请求人工裁决
---
2.9 Memory：Agent 外部认知状态
2.2.5 Memory：Agent 外部认知状态
Memory 不是简单存几个结构化字段。
错误理解：
{
@@ -348,74 +175,39 @@ reusable_lessons.md
哪些样本适合评测集
哪些样本只适合训练集
哪些模型错误模式反复出现
判断系统是否真正 Agent-native 的关键标准之一：
下一次遇到类似问题，Agent 是否明显更聪明。
---
2.10 Policy：权限与人工裁决边界
2.2.6 Policy：权限与人工裁决边界
[图片]
Agent 可以自主推进任务，但不能无限自由。
需要明确哪些事情 Agent 可以自动做，哪些必须人类确认。
暂时无法在小米办公Pro文档外展示此内容
核心原则：
Agent 负责探索和建议；
人负责业务边界裁决。
动作
权限
读取需求文档
自动
读取历史标签定义
自动
查询脱敏线上 session
自动
挖候选样本
自动
聚类去重
自动
预打标
自动
生成边界分析
自动
生成标签定义修订建议
自动
修改标签边界
人工确认
样本入库抽检
人工确认
修改历史数据资产
人工确认
---
3. 人的角色
人不再是流程执行者。
人不应该做：
手写 prompt
手动拼关键词
手动捞数据
手动合并 Excel
大量刷 easy case
手动维护所有边界记忆
人应该做：
裁决业务边界
确认标签定义变更
审核 golden set 入库
处理高分歧样本
处理高流量低置信样本
确认模型回放结论
一句话：
人是边界裁判，不是数据流水线工人。
---
4. Agent 应该如何向人提问
Agent 不应该问：
下一步怎么办？
而应该提出可裁决问题。
示例：
边界裁决问题：
“导航到最近的停车场”应该标为 FAST_DIRECT 还是 SLOW_FILTER_RANK？
候选判断：
A. FAST_DIRECT
理由：最近可以视为导航系统默认距离排序，快系统可以直接执行。
B. SLOW_FILTER_RANK
理由：最近也是排序条件，请求涉及候选集合选择。
Agent 建议：A
原因：
当前快系统导航 POI 默认支持距离优先，因此“最近的停车场”不应等同于“最大的停车场 / 评分最高的停车场”这类优化筛选请求。
请确认：
1. 接受 A
2. 改为 B
3. 补充新的边界规则
人工裁决后，Agent 写入：
memory/human_decisions.md
长期标签边界知识库
相关 skill 的 known-confusions.md
以后类似问题直接复用。
---
5. 典型运行方式
2.3 典型运行方式
[图片]
用户输入：
@@ -438,116 +230,162 @@ Agent 启动任务 workspace。
14. 生成候选评测集
15. 生成回放报告
16. 沉淀 reusable_lessons.md
注意：这不是预设流程，而是一个典型任务可能自然形成的行动轨迹。
---
6. 关键产物
第一版系统建议产出以下文件：
3. 第一阶段目标
- 基于现有 Agent 底座完成最小运行环境搭建，并优先打通三条主要的数据开发链路：
- 需求 / badcase 反馈 → 生成式构建专项评测集 → 数据持久化
- 需求 / badcase 反馈 → 挖掘线上问题 → 构建专项评测集 → 数据持久化
- badcase 自动收集与分析链路打通
3.1 第一阶段落地方案
第一阶段基于现有 claw-code-agent 作为执行底座，在保留其通用 Agent 能力的基础上，补齐面向中控数据开发场景的输入、检索、生成、落盘和 review 能力。
让 claw-code-agent 从一个通用 code-agent，变成一个能够进入中控数据开发环境并执行真实任务的数据 Agent 底座。
前两周的目标：
在一个受控工作区内完成：
- 读取需求 / badcase
- 检索线上样本
- 生成或筛选评测集候选
- 记录过程和中间判断
- 输出可落盘、可 review 的结果
在这一底座之上，第一阶段优先验证三条真实链路：
- 需求 / badcase 反馈 → 生成式构建专项评测集 → 数据持久化
- 需求 / badcase 反馈 → 挖掘线上问题 → 构建专项评测集 → 数据持久化
- badcase 自动收集与分析链路打通
落地原则：
底层复用
claw-code-agent 现有的 loop、tool calling、session persistence、transcript、compaction、markdown memory 注入、policy hook 等能力已经足够成熟，适合作为底层执行引擎直接复用。
因此，第一阶段不重写主循环，不重写工具调用链，不重写 session 基础设施。
上层收口
当前 claw-code-agent 的默认形态是 coding-first：prompt 偏代码助手，工具面偏泛代码操作，workspace 也更接近 code workspace。
第一阶段要做的不是扩展更多能力，而是把这些默认形态收口成 data-first：让 Agent 更聚焦于数据检索、样本筛选、评测集构建和结果沉淀。
具体任务拆解：
直接复用底层执行内核
这一部分不作为改造重点，只作为底座能力直接承接：
- Agent loop
- session / transcript / file_history
- tool schema + tool execution
- markdown memory 注入基础能力
- hook / policy 基础机制
- compaction / replay 基础设施
这些能力已经能支撑“模型驱动循环 + 工具调用 + 过程追踪”，第一阶段不需要投入主要精力。
需要改造的四个点：
1）把 code workspace 改成 task workspace @王云浩
这是最关键的一步。
当前底座支持 markdown memory，但还没有真正 task-native 的工作区。第一阶段要把任务固定到 /tasks/{task_id}/ 目录下，让输入、记忆、产物和日志都围绕任务目录组织。
2）把 coding-first prompt 改成 data-first prompt @王云浩
当前 system prompt 更强调读代码、改代码、bash、git、验证代码修改。
第一阶段需要改成围绕：
- 需求理解
- 边界分析
- open questions
- 样本挖掘
- 标注 / 裁决
- eval/train set 构造
- 经验沉淀
这些数据任务来组织默认口径。
3）把默认工具集改成最小数据工具集 @武阳
当前工具面过宽，对数据 Agent 初版来说不是增强，而是噪音。
第一阶段要做的是裁出一套 default_data_tool_registry()，只保留必要文件工具和少量数据专用工具，让 Agent 的动作空间收敛。
4）把 coding policy 扩展成数据治理 policy @武阳
当前权限语义更像：
- allow write
- allow shell
- deny tool
- ask user
但数据场景需要更细的治理边界，比如：
- 是否允许查线上样本
- 是否允许导出敏感字段
- 是否允许生成标注任务
- 哪些问题必须人工裁决
- 哪些标签修订必须人工确认
这一部分必须在第一阶段明确下来。
需要重点建设的两层能力：
1）之前挖掘经验通过SKILL的方式进行注入(需要进行实验和验证)
第一阶段 skill 不应再只是 prompt 片段，而应沉淀成目录化 markdown 经验包，至少覆盖：
- 边界判断
- 线上挖掘
- 评测集构建
并采用“元信息先注入，正文按需展开”的方式，避免一次性把全部经验塞进上下文。
2）artifacts 统一沉淀
第一阶段所有关键结果都应统一沉淀到 task workspace 下，而不是只停留在 session json 或临时输出里。
这一步是后续 review、复盘、数据资产化的前提。
目标的形态
/tasks/{task_id}/
goal.md
current_understanding.md
boundary_analysis.md
context/
requirement.md
badcase.md
memory/
open_questions.md
human_decisions.md
failed_attempts.md
reusable_lessons.md
candidate_pool.csv
annotation_queue.csv
eval_set_candidate.jsonl
label_definition_patch.md
replay_report.md
trace.md
skills_used.md
这些产物分为三类：
6.1 Agent / 人类协作产物
goal.md
current_understanding.md
boundary_analysis.md
open_questions.md
human_decisions.md
reusable_lessons.md
6.2 数据资产产物
candidate_pool.csv
annotation_queue.csv
eval_set_candidate.jsonl
6.3 审计与复盘产物
trace.md
skills_used.md
failed_attempts.md
replay_report.md
---
7. MVP 建议
第一版不要做大而全平台。
先验证一个最小闭环：
输入 badcase，Agent 能否自主探索并产出高质量边界问题和候选评测集。
MVP 输入
1. 一批 badcase
2. 当前标签定义
3. 可查询的线上 session / topquery
4. 现有评测集
5. 模型预测结果，可选
MVP 输出
1. boundary_analysis.md
2. open_questions.md
3. human_decisions.md
4. candidate_pool.csv
5. eval_set_candidate.jsonl
6. replay_report.md
7. reusable_lessons.md
MVP 验收标准
1. Agent 能自己识别涉及的标签边界
2. Agent 能自己查找相关历史定义 / 样本
3. Agent 能自己提出挖掘策略
4. Agent 能找出一批有效候选样本
5. Agent 能提出高质量人工裁决问题
6. 人工裁决后，Agent 能继续修正结果
7. 最终候选评测集可被人工抽检使用
8. 本次经验能被后续任务复用
---
8. 成功标准
项目成功不看是否跑通一个固定流程，而看以下能力：
1. Agent 是否能自主理解新需求 / badcase？
2. Agent 是否能主动寻找相关历史定义和裁决？
3. Agent 是否能判断当前问题属于哪些标签边界？
4. Agent 是否能自主决定挖哪些数据？
5. Agent 是否能发现标签定义冲突？
6. Agent 是否能提出高质量人工裁决问题？
7. Agent 是否能生成可用候选评测集？
8. Agent 是否能根据人工裁决修正自己的判断？
9. Agent 是否能沉淀经验？
10. 下一次遇到类似问题，Agent 是否明显更聪明？
最重要的是第 10 点。
如果每次任务都像第一次一样重新开始，那就不是经验驱动。
---
9. 最终结论
working_notes.md
decisions.md
artifacts/
eval_candidates.jsonl
mining_strategy.md
report.md
logs/
agent_trace.md
在这个形态下，Agent 能够围绕一个任务完成：
- 输入读取
- 数据检索
- 样本筛选或生成
- 结果沉淀
- 人工 review 触发
代码改造清单
类型
项目
第一阶段动作
说明
直接复用
Agent loop
保留
不重写主循环
直接复用
session / transcript / compaction
保留
直接复用过程追踪能力
直接复用
tool schema / execution
保留
不改调用链
核心改造
workspace
改造
从 code workspace 收口为 task workspace
核心改造
system prompt
改造
从 coding-first 改为 data-first
核心改造
默认工具集
改造
裁出最小数据工具集
核心改造
policy / human gate
改造
从 coding 权限扩展为数据治理边界
必须新增
skill 机制
新增
目录化 markdown 经验包，按需加载
必须新增
artifacts 沉淀规则
新增
所有关键结果统一沉淀到 task 目录
业务验证
生成式评测集构建
打通
作为第一条真实链路
业务验证
线上问题挖掘
打通
作为第二条真实链路
业务验证
badcase 自动收集分析
打通
作为第三条真实链路
[图片]
本项目不应该定义为：
用 Agent 编排快慢系统评测集构建流程
而应该定义为：
给路由数据开发建设一个 Agent-native 工作环境。
最终形态是：
Router Data Agent Workbench
它的核心不是流程，而是：
Workspace
Skills
Resources
Tools
Memory
Policy
它要实现的能力是：
需求 / badcase
→ Agent 自主探索
→ 发现边界问题
→ 挖掘候选数据
→ 提出人工裁决
→ 生成评测 / 训练资产
→ 回放验证
→ 沉淀经验
→ 下次复用
一句话总结：
不是让 AI 跑数据流程，而是让 Agent 拥有一个可以自主完成数据开发工作的环境。