Important
BearAgent 当前还不能执行真实 Agent 任务。仓库已经实现内部数据类型、Run/Activity 状态、Event Reducer、预算检查、SQLite EventStore、首个 OpenAI Responses adapter 和本地文档站；文件工具、 ContextBuilder、完整 Agent Loop 与 Run CLI 仍在 P1 计划中。
假设用户提出：
阅读
docs/中的架构和路线图，写一份项目介绍到outputs/intro.md。
模型可以决定下一步读哪个文件，但它不应该自行决定能否读取任意路径、能否写到仓库其他位置， 也不能在工具超时后猜测文件是否已经写好。BearAgent 在模型之外提供一个 Runtime，负责：
- 保存模型调用、工具操作、预算、错误和产物，使执行过程能够还原；
- 只有在结果能够确认时才继续，无法确认的外部写入停下来处理；
- 根据明确规则检查权限，模型和工具输出都不能给自己增加权限。
第一个可用场景是仓库与本地文档研究。P1 只读取指定工作区，并且只向 outputs/** 写入。
BearAgent 不以复刻 Manus、Claude Code 或堆叠模型、工具和 Agent 角色为目标。
核心 Runtime 只使用 BearAgent 自己的 ID、Message、Event 和接口。具体模型 SDK、SQLite、CLI 和 未来的 HTTP API 都在外层 adapter 中。所有会改变外部世界的操作都经过统一的工具执行和权限入口。
详细说明见总体架构。图中的阶段标签表示路线图目标，不表示对应 模块已经实现。
| 已有代码 | P1 还要接通 | 更晚再做 |
|---|---|---|
| Python 3.12 + uv 工程与 CI | Tool 接口、Registry 与统一 executor | P2：崩溃恢复、Attempt、UNKNOWN |
help、version、doctor |
工作区读取、搜索与 outputs/** 写入 |
P3：Approval、隔离执行、安全自托管 |
| 类型化 ID、Message、Error、Event | outputs/** 原子写入与 Artifact |
P4：Skill、MCP、Web、Memory |
| Run/Activity 状态与五类预算 | ContextBuilder 与有界 Agent Loop | P5：持续追踪与跨版本评测 |
| SQLite EventStore、projection 与 migration | run、inspect、events |
P6+：多个 Agent、浏览器、分布式执行 |
| ModelProvider port 与 OpenAI Responses adapter | 固定任务集与可复现结果 | 只有真实需求出现后再扩展 |
| 中文 Starlight 文档站 | 端到端固定任务集 | 只有真实需求出现后再扩展 |
需要先安装 uv：
git clone https://github.com/CherryYang05/BearAgent.git
cd BearAgent
uv python install 3.12
uv sync --all-groups --locked
uv run bearagent --help
uv run bearagent doctor机器可读诊断：
uv run bearagent doctor --json
uv run python -m bearagent doctor --jsonuv run ruff format --check .
uv run ruff check .
uv run pyright
uv run pytest
uv run python scripts/check_docs.py本地启动中文文档站：
npm --prefix=site ci
npm run dev --prefix=site访问 http://localhost:4321/zh-cn/。生产构建使用 npm run build --prefix=site。
src/bearagent/
├── domain/ BearAgent 自己的 ID、消息、事件、状态和错误
├── runtime/ Reducer、预算和后续执行规则
├── application/ 启动或查询 Run 的用例
├── ports/ Runtime 需要模型、工具、存储提供的行为
├── adapters/ Provider、SQLite、文件和测试实现
└── interfaces/ CLI；HTTP API 后置
测试按要验证的边界放在 tests/unit/、contract/、integration/、recovery/、security/。
| 阶段 | 用户得到什么 | 状态 |
|---|---|---|
| P0 工程基础 | 仓库可安装、测试，开发规则明确 | 已完成 |
| P1 可检查执行 | 本地文件任务可完成，过程和失败可查看 | 进行中 |
| P2 失败恢复 | 中断后只从能确认的位置继续 | 未开始 |
| P3 权限与隔离 | 危险操作获准后执行，代码与宿主隔离 | 未开始 |
| P4 日常使用 | Skill、MCP、Web、Memory 依次接入 | 未开始 |
| P5 持续评测 | 比较质量、成本、恢复和安全回归 | 未开始 |
P3 是第一个可信 Runtime 完成线，不是成熟通用 Agent 产品的完成线。完整验收条件见 项目路线图。
- 产品定位：为谁解决什么问题，为什么范围保持很小；
- 总体架构：模块怎样连接，哪些边界长期成立；
- Feature Specs：每个功能必须做到什么；
- Implementation Plans：按什么顺序实现和验证；
- ADRs：为什么选择当前技术方案；
- AI 辅助开发流程：怎样调查、定义、实现和关闭 Feature；
- 本地文档站：面向学习和代码阅读的中文站点。
docs/、代码和测试保存工程事实；site/ 用更连贯的例子解释这些事实。路线图和参考项目的能力
不能被写成当前实现。
先阅读 AGENTS.md，再确认当前 Feature 的 Spec、ADR 和 Plan。修改保持范围清楚，
并用与风险相称的单元、契约、集成、恢复和安全测试证明行为。Feature 完成时同步工程文档、学习
说明、开发者入口和当前状态。
许可证尚未决定。公开发布代码前会在 Apache-2.0 与 AGPL-3.0 之间通过 ADR 确认；在此之前， 不要假设拥有复制、修改或分发授权。