{"id":49360334,"url":"https://github.com/rustypiano/tiny-agent","last_synced_at":"2026-04-27T16:01:46.210Z","repository":{"id":349263967,"uuid":"1201106023","full_name":"RustyPiano/tiny-agent","owner":"RustyPiano","description":null,"archived":false,"fork":false,"pushed_at":"2026-04-05T02:21:53.000Z","size":209,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-04-05T04:20:47.008Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/RustyPiano.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-04-04T08:09:21.000Z","updated_at":"2026-04-05T02:21:57.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/RustyPiano/tiny-agent","commit_stats":null,"previous_names":["rustypiano/tiny-agent"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/RustyPiano/tiny-agent","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/RustyPiano%2Ftiny-agent","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/RustyPiano%2Ftiny-agent/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/RustyPiano%2Ftiny-agent/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/RustyPiano%2Ftiny-agent/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/RustyPiano","download_url":"https://codeload.github.com/RustyPiano/tiny-agent/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/RustyPiano%2Ftiny-agent/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":32343571,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-26T23:26:28.701Z","status":"online","status_checked_at":"2026-04-27T02:00:06.769Z","response_time":128,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2026-04-27T16:01:45.008Z","updated_at":"2026-04-27T16:01:46.200Z","avatar_url":"https://github.com/RustyPiano.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Agent Framework\n\n轻量 Python Agent，不依赖第三方框架（仅 anthropic/openai SDK）。\n\n## 前置条件\n\n- Python 3.11+\n- Anthropic 或 OpenAI API Key\n\n## 安装方式\n\n最短路径：\n\n```bash\ngit clone https://github.com/RustyPiano/tiny-agent.git\ncd tiny-agent\n# 进入仓库根目录后再安装和运行\npip install -e .\nexport ANTHROPIC_API_KEY=xxx\nagent\n```\n\n如果你要做开发、跑测试或改代码，安装开发依赖：\n\n```bash\npip install -e \".[dev]\"\n```\n\n如果你只想运行，不需要开发工具：\n\n```bash\npip install -e .\n```\n\n## 快速开始\n\n```bash\n# 配置 API Key\nexport ANTHROPIC_API_KEY=xxx\n\n# 运行（推荐）\nagent\n\n# 或模块方式\npython -m agent_framework\n```\n\n运行后应看到类似输出：\n\n```\nAgent 已启动，输入任务（Ctrl+C 退出）：\n\n你:\n```\n\n## 用法\n\n```bash\n# 基本用法\nagent\n\n# 使用 OpenAI provider\nagent --provider openai --model gpt-4o\n\n# 使用本地模型 (Ollama)\nagent --provider openai --model qwen2.5:14b --base-url http://localhost:11434/v1\n\n# 预加载 skills（可选；skills 名称来自已发现目录）\nagent --skills code-review,safe-ops\n\n# 持久化会话\nagent --session my_project\n\n# 界面模式\nagent --ui concise\nagent --ui detailed\n\n# JSON 日志格式\nagent --log-format json --log-level DEBUG\n```\n\n## 架构\n\n```\nagent-framework/\n├── agent_framework/\n│   ├── __main__.py         # python -m agent_framework 入口\n│   ├── main.py             # CLI 入口（project.scripts: agent）\n│   ├── _config.py          # 配置集中化\n│   ├── core/               # 核心组件\n│   ├── llm/                # Provider 抽象层\n│   ├── tools/              # 工具系统\n│   ├── skills/             # Skill 系统\n│   ├── sessions/           # 会话持久化\n│   └── extensions/         # 扩展加载器与内置扩展示例\n├── tests/\n└── pyproject.toml\n```\n\n### 核心概念\n\n- **ReAct 循环**: `agent_framework/core/agent.py` 实现 Reasoning-Acting 循环\n- **Provider 抽象**: `agent_framework/llm/base.py` 定义统一接口\n- **工具注册**: `agent_framework/tools/registry.py` 提供声明式工具注册\n- **Skill 注入**: `agent_framework/skills/` 动态注入 prompt 片段\n\n## LiteAgent 哲学对齐\n\n- 静态 system prompt 现在声明了严格 ReAct JSON 契约（`\"thought\"` / `\"action\"` / `\"action_input\"`）。\n- prompt 明确了运行时注册工具集合、安全约束和上下文纪律（轮次/历史/记忆边界）。\n- 静态区域显式引用 `__SYSTEM_PROMPT_DYNAMIC_BOUNDARY__`，用于区分静态契约与运行时动态上下文。\n- 相关测试是轻量 anti-regression 护栏（检查关键条款是否存在），不等价于对模型行为做完整语义验证。\n- `workspace_root` 和 `sessions_dir` 由 `AgentSettings` 注入到 runtime 和工具层，不再只依赖全局配置。\n- 详细说明见 `docs/liteagent-philosophy-alignment.md`。\n\n## 扩展指南\n\n- [如何新增 Tool](docs/how-to-add-tool.md)\n- [如何新增 Provider](docs/how-to-add-provider.md)\n- [如何新增 Skill](docs/how-to-add-skill.md)\n\n## 扩展机制（PoC）\n\n框架会在启动时按约定目录尝试加载扩展模块：\n\n- `agent_framework/extensions/tools/*.py`\n- `agent_framework/extensions/providers/*.py`\n\n扩展模块需要提供模块级 `register()` 合约函数，加载器会导入模块后调用该函数完成注册。\n\n启动时会把当前已注册工具集合动态写入 prompt 的 allowed-tools 段，因此扩展工具一旦注册，就会进入模型可见的工具列表。\n\n安全说明（重要）：扩展本质上是 Python 代码，加载时会执行任意模块代码与 `register()` 逻辑。请仅安装和启用你信任来源的扩展。\n\n## 开发\n\n```bash\n# 运行测试\nmake test\n\n# 代码检查\nmake lint\n\n# 类型检查\nmake type\n\n# 全部检查\nmake check\n\n# 清理缓存\nmake clean\n```\n\n## 配置\n\n环境变量：\n\n| 变量 | 说明 | 默认值 |\n|------|------|--------|\n| `ANTHROPIC_API_KEY` | Anthropic API Key | - |\n| `OPENAI_API_KEY` | OpenAI API Key | - |\n| `AGENT_PROVIDER` | Provider 类型 | `anthropic` |\n| `AGENT_MODEL` | 模型名称 | `claude-opus-4-6` |\n| `AGENT_BASE_URL` | 自定义 API 地址 | - |\n| `AGENT_WORKSPACE` | 工作空间根目录 | 当前目录 |\n| `AGENT_PROJECT_SKILLS_DIR` | 项目级 skills 目录 | `\u003cworkspace\u003e/.agents/skills` |\n| `AGENT_GLOBAL_SKILLS_DIR` | 全局 skills 目录 | `~/.agents/skills` |\n\n## Skills 目录规范\n\nSkill 采用主流目录布局：\n\n`\u003cskills_root\u003e/\u003cskill_name\u003e/SKILL.md`\n\n`SKILL.md` 顶部使用 frontmatter：\n\n```md\n---\nname: coding\ndescription: 代码实现与重构最佳实践\n---\n\u003cskill 的完整指令正文\u003e\n```\n\n当前解析器是轻量实现，仅支持简单的 `key: value` 行（例如 `name`、`description`），不支持嵌套 YAML 结构或复杂语法。\n\n启动时会自动发现两级 skills 并注入 metadata 到 system prompt 的 `Available Skills` 段落：\n\n1. 全局级：`~/.agents/skills`\n2. 项目级：`\u003cproject\u003e/.agents/skills`\n\n同名 skill 以项目级覆盖全局级（project \u003e global）。\n\n## Skills 加载流程\n\n1. 启动时扫描全局目录与项目目录，读取 `SKILL.md` frontmatter 的 `name`/`description`。\n2. 自动把技能元数据注入 system prompt 的 `Available Skills`。\n3. 当模型需要技能完整内容时，调用 `use_skill(name)` 按需加载正文。\n4. 同名技能按项目级覆盖全局级。\n\n## 会话与工作区\n\n- 文件工具、`run_bash`、`run_job`、`grep`、`list_dir`、`edit_file` 都会使用 `AgentSettings.workspace_root` 作为运行时工作区边界。\n- `run_bash` 用于前台短任务；长时间运行的命令应使用 `run_job` 启动并查询高信号状态。\n- 会话历史由 `AgentSettings.sessions_dir` 决定，嵌入式调用时可以通过 settings 覆盖默认目录。\n- `main.py` 的 CLI 仍然保留当前默认行为，只是底层不再依赖单一全局配置真源。\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Frustypiano%2Ftiny-agent","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Frustypiano%2Ftiny-agent","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Frustypiano%2Ftiny-agent/lists"}