145 lines
5.2 KiB
Markdown
145 lines
5.2 KiB
Markdown
# 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）
|