最核心身份：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`

换句话说，它不是围绕“任务节点图”来设计的，而是围绕：

当前 session 里有哪些上下文
当前模型要不要发起 tool call
tool result 如何再次喂回模型
何时 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，并在每轮前做上下文压力处理：

启动时构建 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
构建初始 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
每轮前的状态整理
- _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 做的事情是：

把 session.to_openai_messages() 和 tool_specs 发给模型，见 src/agent_runtime.py:1153-1157
从返回中解析：
- 普通 assistant content
- tool calls
- finish_reason
- usage
若无 tool call，则视作模型选择直接回答
若有 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，内容是：

{
  "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
每轮内的动作内容是模型驱动的

固定部分是：

整理上下文
预算检查
调模型
若 tool_calls 则执行工具
把工具结果写回 transcript
进入下一轮或停止

动态部分是：

调什么工具
调多少个工具
是继续观察、修改还是直接回答

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 当前设计局限

长期记忆是纯文件注入，不是检索式 memory
- 规模大时容易塞满 prompt
- 没有 relevance ranking
只识别 CLAUDE.md 家族，不识别 AGENTS.md
- 对多代理协作约束不够统一
resume 依赖 transcript replay，不是真正的 semantic memory
- 历史很多时仍然会发生 compaction 丢失细节
runtime summaries 很多，但上下文管理是“全量摘要注入”
- 不是 query-time selective loading
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 会：

解析 tool call，见 src/openai_compat.py:273-298
在 loop 中逐个消费，见 src/agent_runtime.py:808-1119
普通工具走 execute_tool_streaming() 或 tool.execute()，见 src/agent_tools.py:181-207
特殊工具：
- 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

完全可以，而且改造成本不高。

一个可行布局：

/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

最小改造方式：

在 task_runtime 中给 task 增加 task_root
在 agent_context._load_memory_bundle() 中把 /tasks/{active_task}/memory/*.md 纳入 memory discovery
在 prompt context 中注入 active task root
给 update_plan / task 工具增加 task-root 绑定

这样不需要重写 loop，只是增强 workspace memory layout。

6. Skills

6.1 当前是否支持 skill

支持，但属于 弱 skill 系统。

当前 skill 机制分两部分：

Bundled skills
- BundledSkill 定义 name / description / when_to_use / aliases / allowed_tools / get_prompt
- 见 src/bundled_skills.py:22-32
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。

最小改造方案

目录结构

.claude/skills/
  review/
    skill.json
    SKILL.md
  data-agent/
    skill.json
    SKILL.md
  python-debug/
    skill.json
    SKILL.md

metadata

skill.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 时机

建议两阶段：

session 初始化时只加载 metadata
- 像 bundled skill 一样列进 system prompt
- 不把 SKILL.md 正文直接注入
当模型选择 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 还有几个明显缺口：

缺少按数据源级别的权限模型
- 没有“允许读 CSV 但不允许发网络请求”这种更细粒度策略
没有结构化审批流
- 例如“将执行 SQL / 访问线上表 / 导出结果集”的 ask approval 缺位
没有数据脱敏/泄露策略
- safe_env 只管环境变量，不管输出内容
没有审计级 action classification
- tool 结果有 metadata，但没有“高风险数据出站/高风险变更”的统一标签体系
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 还缺什么

目前还缺：

完整 prompt snapshot
- 现在有 system/user context 和 transcript，但缺“每轮实际发给模型的最终 payload”落盘
turn-level structured trace
- 比如 turn_03.json
- 包含 prompt size、tool candidates、selected tool calls、latency、errors
统一 replay viewer
- 现在 resume 偏“继续工作”
- 不是“回放调试”
tool latency / error taxonomy
- 有 event，但缺统计聚合
compaction provenance
- 已有 replay，但缺图形化 lineage/summary mapping

8.7 如果要补，怎么加

最小建议：

建议新增 trace 目录

.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，而是三件事：

workspace skill discovery + on-demand markdown loading
任务目录结构与 memory layout 约定
turn-level trace 持久化与 replay viewer

这三项都可以在不重写 LocalCodingAgent 主循环的前提下增量演进。

README.md Unescape Escape

Claw Code Agent 架构逆向分析报告

1. 总体定位

1.1 这个项目本质上是什么

1.2 核心抽象是什么

1.3 与 Claude Code / Codex 的相似点与差异

相似点

差异点

2. Agent Loop

2.1 主循环入口

2.2 每轮如何观察当前状态

2.3 如何构造上下文

第一层：环境与 memory 采样

第二层：系统提示词装配

2.4 如何决定下一步行动

2.5 如何调用工具

2.6 工具结果如何回到模型上下文

2.7 什么时候停止

2.8 loop 是固定流程还是模型驱动

3. Context / Memory

3.1 是否有短期上下文

3.2 是否有长期记忆

3.3 是否有 conversation history

3.4 是否有压缩 / summarize / compaction

3.5 是否有外部文件作为 memory

3.6 是否支持类似 CLAUDE.md / AGENTS.md / skills 的持久知识

CLAUDE.md

AGENTS.md

skills

3.7 当前设计局限

4. Tools / Actions

4.1 工具能力概览

4.2 工具 schema 怎么定义

4.3 工具调用怎么执行

4.4 工具结果如何返回

4.5 是否有安全边界

文件边界

写权限边界

shell 权限边界

policy / hook deny

CLI 层 deny context

4.6 这一层的架构评价

5. Markdown / Workspace

5.1 是否支持 workspace-first

5.2 是否适合让 Agent 维护 .md 文件作为任务记忆

5.3 是否有任务目录 / workspace 概念

5.4 能否改造成 task directory layout

6. Skills

6.1 当前是否支持 skill

6.2 是否有技能发现机制

6.3 是否支持 progressive disclosure

6.4 如果没有，应该如何扩展

最小改造方案

目录结构

metadata

loading 时机

Agent 如何决定读取哪个 skill

代码落点

7. Policy / Human Gate

7.1 如何处理权限

第一层：启动时权限布尔开关

第二层：workspace hook / policy

第三层：ask_user runtime

7.2 哪些动作会请求用户确认

7.3 哪些动作默认允许

7.4 是否有 deny / allow / ask 策略

7.5 是否支持项目级规则

7.6 对数据 Agent 的不足

8. Trace / Observability

8.1 是否记录每一轮模型输入输出

8.2 是否记录工具调用

8.3 是否记录文件变更

8.4 是否有 replay/debug 能力

8.5 现有 observability 的优点

8.6 还缺什么

8.7 如果要补，怎么加

建议新增 trace 目录

每轮保存这些内容

代码落点

总结判断

README.md

5.2 是否适合让 Agent 维护 `.md` 文件作为任务记忆