|
|
# 04 最小复刻清单
|
|
|
|
|
|
目标：一个你能完全讲清楚的小 Agent，不是功能全集。
|
|
|
|
|
|
建议包名 / 命令：自己定，下文用 `myagent` 指代。
|
|
|
|
|
|
## 1. 目录骨架
|
|
|
|
|
|
```text
|
|
|
my-agent/
|
|
|
pyproject.toml
|
|
|
README.md
|
|
|
src/myagent/
|
|
|
__init__.py
|
|
|
cli.py # argparse：--model / --session
|
|
|
config.py # 读环境变量或用户目录 ini/yaml
|
|
|
llm.py # 只创建 ChatOpenAI(base_url, api_key, model)
|
|
|
prompt.py # 静态 system + 动态 cwd/tree
|
|
|
graph.py # StateGraph：llm_call / tool_node
|
|
|
tools/
|
|
|
fs.py # read_file, list_dir, replace_in_file
|
|
|
shell.py # execute_command + 确认回调
|
|
|
session.py # sqlite checkpointer
|
|
|
tests/
|
|
|
test_graph_smoke.py
|
|
|
test_path_sandbox.py
|
|
|
```
|
|
|
|
|
|
第一版**不要**：textual、mcp、skills、subagent、语音、多厂商。
|
|
|
|
|
|
## 2. 配置（最小）
|
|
|
|
|
|
环境变量即可：
|
|
|
|
|
|
```text
|
|
|
MYAGENT_API_KEY=...
|
|
|
MYAGENT_BASE_URL=https://api.agicto.cn/v1
|
|
|
MYAGENT_MODEL=deepseek-v4-flash
|
|
|
```
|
|
|
|
|
|
密钥只放用户目录或系统环境，禁止进 git。
|
|
|
|
|
|
## 3. 图的最小实现要点
|
|
|
|
|
|
```text
|
|
|
State = { messages, llm_calls }
|
|
|
|
|
|
START → llm_call → (有 tool_calls?)
|
|
|
是 → tool_node → llm_call
|
|
|
否 → END
|
|
|
```
|
|
|
|
|
|
硬性要求：
|
|
|
|
|
|
- 工具异常要变成 ToolMessage 文本，不能把整个图打崩
|
|
|
- 一轮多个 tool_calls 可以先串行，跑通再并行
|
|
|
- `thread_id` 用参数传入，默认 `default`
|
|
|
|
|
|
## 4. 工具验收
|
|
|
|
|
|
| 工具 | 必须有的约束 | 怎么测 |
|
|
|
|------|----------------|--------|
|
|
|
| read_file | 只能读 cwd 内；限制行数 | 读 `../` 应拒绝 |
|
|
|
| list_dir | 跳过 `.git` / `node_modules` / `.venv` | 在本项目根目录跑 |
|
|
|
| replace_in_file | old_text 必须唯一匹配 | 改一个函数名再读回来 |
|
|
|
| execute_command | 超时；打印命令等 y/N | 输入 `n` 应取消 |
|
|
|
|
|
|
## 5. CLI 体验（第一版足够）
|
|
|
|
|
|
```text
|
|
|
$ myagent
|
|
|
> 请总结当前目录 README
|
|
|
[think] ...
|
|
|
[tool] read_file README.md
|
|
|
[final] ...
|
|
|
|
|
|
> /clear
|
|
|
> /exit
|
|
|
```
|
|
|
|
|
|
没有气泡也没关系。日志清晰比好看重要。
|
|
|
|
|
|
## 6. 测试底线
|
|
|
|
|
|
- `test_path_sandbox.py`：逃出 cwd 失败
|
|
|
- `test_graph_smoke.py`：mock LLM 返回一次 tool_call 再返回纯文本，断言 tool 被调用、最终 END
|
|
|
|
|
|
没有 mock 测试，不要进入阶段 4。
|
|
|
|
|
|
## 7. 对照 Qoze 时允许借鉴的“形状”
|
|
|
|
|
|
可以借鉴：
|
|
|
|
|
|
- 两节点 ReAct 图
|
|
|
- 静态/动态 prompt 分离
|
|
|
- 文件路径沙箱
|
|
|
- checkpoint 的 thread_id 思路
|
|
|
|
|
|
不要复制：
|
|
|
|
|
|
- 整份 `system_prompt.py` 长文案
|
|
|
- Textual CSS 和像素 logo
|
|
|
- 十几个厂商的 `initialize_llm` 分支
|
|
|
- 被注释掉的浏览器工具堆
|
|
|
|
|
|
## 8. 完成定义（Definition of Done）
|
|
|
|
|
|
当下面全是“是”，阶段 3 才结束：
|
|
|
|
|
|
- [ ] 新仓库能独立 `pip install -e .` 跑起来
|
|
|
- [ ] 只用 DeepSeek 兼容接口
|
|
|
- [ ] 四件套工具都有单测或手工脚本
|
|
|
- [ ] 会话可恢复
|
|
|
- [ ] README 是你自己写的架构说明（不是拷来的）
|
|
|
- [ ] 你能不看代码画出数据流
|
