58 lines
4.4 KiB
Markdown
58 lines
4.4 KiB
Markdown
# Agent-Squad 项目事实
|
|
|
|
工作规则见 [AGENTS.md](AGENTS.md)。此文件维护本项目事实，不复制通用规范。
|
|
|
|
## 仓库与操作
|
|
|
|
- 目标/产品边界：通用智能体小队编排底座。角色、蓝图、规划、执行引擎、黑板、HITL 与 HTTP/CLI 组合根。不含预设医疗器械角色或任务模板。不实现 Agent。
|
|
- 源码、资产、文档、机器契约位置：Go 模块路径 `agent-squad`。包为 `squad`、`store`、`server`、`cli`、`textextract`、`conformance`。人类文档在根 `README.md`、`policy/`；过程记录在 `docs/records/`。对外 HTTP 错误合同以错误码库信封为准。
|
|
- 权威远端、集成基线、受保护分支：`ssh://git@git-ssh.u1680832.nyat.app:31411/weichen/Agent-Squad.git`，集成基线 `main`。
|
|
- 并行共同基线记录位置、合入通知/主动检查方式：Gitea Issue/PR。跨仓共同起点是本仓提交加上它锁定的 Agent-Native、错误码库、日志库与规范库 SHA。
|
|
- 发布线与批准版本/实际制品查询入口：无独立制品库。可执行文件由 `go build` 从固定 gitlink 组合产出。
|
|
- 提交/审核/合并/发布身份与权限：仓库所有者 weichen。
|
|
- 任务唯一来源：Gitea `weichen/Agent-Squad` 的 Issue 与 Pull Request。
|
|
- 规范性文档目录：`policy/`。
|
|
- 过程文档仓/目录：任务卡与交付证据在 `.task/`（模板 `.task/templates/task-card.md`）；其他过程记录在 `docs/records/`（项目内豁免，见采纳记录）。
|
|
- 交接记录位置：随任务主记录；需要落盘的任务交接与交付证据放入 `.task/`，其他落盘交接放入 `docs/records/`。
|
|
- 凭证查找入口及所需字段：LLM 使用环境变量 `AGENT_SQUAD_LLM_BASE_URL`、`AGENT_SQUAD_LLM_API_KEY`、`AGENT_SQUAD_LLM_MODEL`。日志采集 token 使用日志库自己的配置。文档与仓库不记录这些值。
|
|
|
|
## 依赖组合
|
|
|
|
| 逻辑 ID | 路径 | 角色 |
|
|
|---|---|---|
|
|
| agent-native | `deps/agent-native` | build-required |
|
|
| agent-intent | `deps/agent-intent` | build-required，可选意图闸门（`squadintent` 适配器；未配置意图时行为与原实现一致） |
|
|
| development-guidelines | `deps/development-guidelines` | development-only |
|
|
| error-code-system | `deps/error-code-system` | build-required |
|
|
| logging-system | `deps/logging-system` | build-required |
|
|
|
|
`go.mod` 的 `replace` 都指向 `./deps/`。嵌套在 `deps/agent-native/deps/`、`deps/agent-intent/deps/` 里的同名副本不参与本仓编译，提交必须与本仓 gitlink 一致（`scripts/submodule-consistency.sh`）。
|
|
|
|
同一 run 的临界区在 unix 上额外持有 `runs/<id>/.lock` 的 flock，拿不到锁时返回 `ErrRunBusy`。非 unix 平台没有这把文件锁，只保留进程内互斥。
|
|
|
|
克隆：
|
|
|
|
```bash
|
|
git clone --recurse-submodules ssh://git@git-ssh.u1680832.nyat.app:31411/weichen/Agent-Squad.git
|
|
# 已克隆时：git submodule update --init --recursive
|
|
```
|
|
|
|
## 验证命令
|
|
|
|
| 影响 | 工作目录与真实命令/CI | 前提与不覆盖范围 |
|
|
|---|---|---|
|
|
| 文档 | 人工核对入口与相对链接 | 不证明运行时行为 |
|
|
| 模块/接口 | 仓库根：`GOWORK=off go vet ./... && GOWORK=off go test -count=1 ./...` | 需要已初始化的 Agent-Native 子模块；默认 stub，不调用真实模型 |
|
|
| 数据/权限/恢复 | conformance 与 store 测试覆盖运行落盘、HITL 恢复 | 无共享数据库 |
|
|
| UI/执行后端 | `GOWORK=off go test -count=1 ./server/... ./conformance/...` | 不覆盖浏览器；SSE 由测试客户端验证 |
|
|
| 治理与 Agent 执行配置 | 仓库根：`scripts/agent-exec validate --repo .` 与 `scripts/dm governance check --repo .` | 需 `deps/development-manager` 已按 gitlink 检出（首次 `dm` 调用会构建 dm-server）；只核验 AGENT-EXECUTION.md 与治理文件，不证明实施单元正确 |
|
|
|
|
## 环境与数据
|
|
|
|
| 环境/实例 ID | 只读查询入口 | 授权写入入口 | DB/存储归属 | 恢复入口 |
|
|
|---|---|---|---|---|
|
|
| 本地开发 | `go test` 与 CLI `runs inspect` | CLI / `POST /v1/runs` 写入调用方指定数据目录 | 运行目录 `<data>/runs/<run_id>/`，无共享 DB | 进程重启后 `POST /v1/runs/{id}/resume`，磁盘为权威 |
|
|
|
|
共享项及 ACL：无。部署、迁移、发布的审批依据与负责角色：库本身不部署；`agent-squad serve` 仅作本地组合根，合并进 `main` 由仓库所有者批准。
|
|
实际制品/配置/schema 的查询方法：以当前 `main` 的 `squad` 模型与 HTTP 路由为准。
|