# AgentAdmin 项目文档

这里是 AgentAdmin 的项目级文档入口。文档由 Git 管理，直接随代码更新；本项目不要求同步 Wiki、创建工单或经过额外审批。

## 建议阅读顺序

1. [项目概况](00-project-profile.md)：项目定位、技术基线和边界。
2. [开发工作流](01-workflow.md)：从理解需求到验证交付的轻量流程。
3. [架构与代码地图](02-architecture-and-code-map.md)：模块职责、数据流和修改影响。
4. [业务规则与术语](03-business-rules-and-glossary.md)：当前稳定规则和统一名称。
5. [本地开发与验证](04-local-development-and-verification.md)：环境、构建和测试命令。
6. [常见改动指南](05-common-changes.md)：按改动类型定位代码和测试。
7. [排障指南](06-troubleshooting.md)：常见问题的最短检查路径。

## Agent 规范

任务协议和动作是独立的可执行规范，从 [Agent 文档](agent/README.md) 开始阅读：

- [协议结构](agent/protocol.md)
- [选择器](agent/selector.md)
- [变量、输出与断言](agent/values-and-outputs.md)
- [执行语义](agent/execution.md)
- [动作索引](agent/actions/README.md)
- [后续能力](agent/roadmap.md)

`agent/` 中部分文档描述了目标设计。是否已经可用，以动作索引中的实现状态和当前代码为准。

## 事实来源

发生冲突时，按以下方式处理：

- 用户当前确认的需求决定本次交付范围。
- [AGENTS.md](../AGENTS.md) 记录仓库长期开发规则。
- Gradle 配置、Manifest 和代码决定当前实际行为与版本。
- `docs/agent/` 记录任务协议和动作约定，但未实现能力不能仅靠文档或 JSON 启用。

发现不一致时，应在同一次相关改动中修正文档、实现或测试，不保留互相矛盾的说明。

## 文档维护

- 修改运行行为时，同步更新对应项目文档和 Agent 规范。
- 新增动作时，同步更新模型、解析、执行器、动作页和测试。
- 只记录已经确认的事实；未确定事项放入后续能力文档，并明确为待定。
- 避免复制同一份详细规则；项目级文档负责导航和代码地图，动作细节留在 `docs/agent/`。