# Agent-System 项目地图

> 通用 Agent 工作方式见 [AGENTS.md](./AGENTS.md)。  
> Claude Code 入口见 [CLAUDE.md](./CLAUDE.md)。

---

## 1. 产品一句话

面向企业与团队的多用户工作流与对话智能体平台：RAG 知识库、PI Agent 执行、项目治理、阶段门禁、文档审批、任务持久化与 SSE 流式交互。

---

## 2. 主要目录

| 路径 | 说明 |
|------|------|
| `cmd/` | 服务入口 |
| `internal/` | Go 业务逻辑（server、coordinator、bizdev、chat、projectinstance 等） |
| `web/` | React + Vite 前端 |
| `deploy/postgres/goose/` | PostgreSQL 迁移（Goose） |
| `configs/` | Agent 与提示词配置 |
| `templates/` | 工作流文档模板 |
| `.doc/` | 架构、审计、整改文档 |
| `.doc/ops/` | **活协作区**（CURRENT、任务、checklist、handoff） |
| `.doc/test-reports/` | 测试/验收报告（归档） |
| `data/dev|test|main/` | 各环境对话与工作区（隔离） |
| `scripts/` | 运维与推送脚本 |

---

## 3. 技术栈

- **后端**：Go HTTP API（~110 路由）
- **前端**：React + Vite
- **数据库**：PostgreSQL + pgvector（Goose 迁移）
- **产品执行器**：容器内 PI Agent Runner（真实 / stub）
- **工程协作**：Herdr 管理的 Claude / Codex / Cursor / Antigravity / PI / Kimi / Cline；其中 Herdr PI 与产品 PI Agent Runner 无关
- **工作流**：main、product_manager、test_manager 三套正式定义

---

## 4. Git 三分支与三环境

详见 [.cursor/rules/git-workflow-and-environments.mdc](./.cursor/rules/git-workflow-and-environments.mdc)。

| 环境 | 分支 | Compose | HTTP | DB 端口 | 数据路径 |
|------|------|---------|------|---------|----------|
| 开发 | dev | agent-dev | 8080 | 5433 | data/dev |
| 测试 | test | agent-test | 8081 | 5434 | data/test |
| 生产 | main | agent-main | 8000 | 5435 | data/main |
| 共享 KB | 跨环境 | agent-infra | - | 5432 | data/shared/kb |

**红线**：知识库共享；对话与业务 DB **严格隔离**，禁止跨环境读写。

**分支红线**：三大主干（`dev`/`test`/`main`）禁止直接开发 commit；一律从 `dev` 开 `feature/*` 或 `fix/*`，合回 `dev` 须占集成槽位（见 [AGENTS.md](./AGENTS.md) §6）。

---

## 5. 文档地图（SSOT）

| 用途 | 路径 |
|------|------|
| 文档总地图 | [.doc/README.md](./.doc/README.md) |
| 协作会话 / 当前焦点 | [.doc/ops/CURRENT.md](./.doc/ops/CURRENT.md) |
| 模块完成度 | [.doc/status/FEATURE-MATRIX.md](./.doc/status/FEATURE-MATRIX.md) |
| 发布/审计缺口 | [.doc/remediation/gap-matrix.md](./.doc/remediation/gap-matrix.md) |
| 问题分析 | [.doc/audit/INDEX.md](./.doc/audit/INDEX.md) |
| 整改方案 | [.doc/remediation/INDEX.md](./.doc/remediation/INDEX.md) |
| 测试报告归档 | [.doc/test-reports/](./.doc/test-reports/) |
| 测试报告规范 | [.cursor/rules/test-reports-standard.mdc](./.cursor/rules/test-reports-standard.mdc) |
| Herdr 角色与备援 | [.doc/ops/2026-09-13-herdr-agent-roster.md](./.doc/ops/2026-09-13-herdr-agent-roster.md) |

---

## 6. 常用命令

```bash
# 环境
./scripts/env-service.sh shared start
./scripts/env-service.sh dev start
./scripts/env-service.sh all status

# Go 质量门禁（默认）
go vet ./...
go test -short ./...

# PG 集成（需 TEST_DATABASE_URL）
TEST_DATABASE_URL=postgres://... go test ./internal/server/... -run 'TestE2E_WorkflowGovernance'

# 真实 PI E2E（显式开关）
RUN_PI_E2E=1 RUNNER_AUTH_TOKEN=... go test ./... -run 'PI'

# 前端
cd web && npm test && npm run build

# 数据库迁移
# 见 deploy/postgres/goose/
```

---

## 7. Git 推送（自主，勿索要 token）

- **脚本**：[`scripts/git-push-dev.sh`](./scripts/git-push-dev.sh)
- **凭证文件**：`${HOME}/.secrets/gitea`
- **字段**：
  ```text
  - ACCESS_TOKEN=<token>
  - URL_PREFIX=<host>
  ```
- **用法**：`./scripts/git-push-dev.sh dev`（或 test/main 分支名）

---

## 8. 测试与验收铁律

- 开发可用 stub；**交付前验收**必须真实 PI Agent + MiniMax-M2.7-highspeed 全链路
- 报告必须归档至 `.doc/test-reports/`，遵循 test-reports-standard
- 禁止 stub 输出冒充最终验收数据

---

## 9. 当前焦点（动态）

见 **[.doc/ops/CURRENT.md](./.doc/ops/CURRENT.md)**。

- 发布缺口 SSOT：[gap-matrix](./.doc/remediation/gap-matrix.md)
- 模块完成度：[FEATURE-MATRIX](./.doc/status/FEATURE-MATRIX.md)
- 最新测试报告：[2026-09-13-codex-audit-p0-remediation-test-report.md](./.doc/test-reports/2026-09-13-codex-audit-p0-remediation-test-report.md)
- **剩余 blocker**: 对话刷新恢复与历史读取授权一致性 + CI 真实 PI E2E + 前端人工抽检（main 本地冒烟已通过）

---

## 10. Herdr 工程协作

- `orchestrator_codex` 负责拆解、方案、调度、风险控制和终审；主力实现默认交给 `implementer_cursor`。
- 启动实例用 `scripts/herdr-agent-start.sh`，派发与安全降级用 `scripts/herdr-agent-dispatch.sh`。
- 角色和备援 SSOT 见 [Herdr Agent roster](./.doc/ops/2026-09-13-herdr-agent-roster.md)。

## 11. 语言与提交

- 对用户：**简体中文**
- 提交：Conventional Commits；在 `feature/*` 或 `fix/*` 上渐进式分批提交，合回 `dev` 用 `--no-ff`（禁止在三大主干直接 commit）