# Agent-System 项目入口

工作边界见 [AGENTS.md](./AGENTS.md)（Gitea 原生门禁模型）。本仓库是 Go + React/Vite + PostgreSQL/pgvector 的多用户工作流与对话平台，产品执行器为容器中的产品 PI Agent Runner。

## 仓库地图

| 路径 | 用途 |
|---|---|
| `cmd/`、`internal/` | 服务入口与 Go 模块 |
| `web/` | React/Vite 前端 |
| `deploy/postgres/goose/` | Goose 数据库迁移 |
| `configs/`、`templates/` | 运行配置、提示词与工作流模板（变更可能需要运行验收） |
| `scripts/` | 工程、环境与推送工具 |
| `.doc/` | [文档地图](./.doc/README.md)、任务与证据 |
| `data/dev`、`data/test`、`data/main` | 各环境独立业务数据与工作区 |

模块编码/接口调整前读 [模块开发标准](./.doc/system-design/2026-09-20-module-development-standards.md)，遵守既有接口、事件和表写者边界。

## 环境与操作入口

| 环境 | 分支 | 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 |

这是拓扑约定，实际端口/制品/config/schema 由目标环境收据核实。知识库共享；对话、工作区、审计及业务 DB 严格隔离，禁止跨环境读写。

创建任务、合入、环境写操作与清理遵循 [AGENTS.md](./AGENTS.md) 的 PR 模型：功能分支 → PR（必需 CI + 非作者批准）→ 合入；不再依赖本地治理工具链。旧 [worktree 操作规范](./.doc/ops/2026-09-21-agent-worktree-workflow.md) 保留为历史参考。只读环境查询入口为 `./scripts/env-service.sh all status`；共享服务写操作在主运行入口执行。晋升到 test/main 单独授权。

## 验证入口

按 [验证契约](./.doc/ops/2026-09-21-validation-contract.md) 选测试、精确用例、模型证据和报告层级。普通文档只做差异/链接/状态一致性；运行模板/提示词按运行内容验收。

- Go：`./scripts/arch-check.sh --mode block`、`go vet ./...`、`go test -short ./...`；按范围追加 PG/鉴权负例。
- 前端：在 `web/` 执行 `npm test`、`npm run build`；交互变更追加受影响真实浏览器测试。
- 产品 Agent/工作流：真实产品 PI Agent Runner；[nightly 入口](./scripts/run-nightly-real-pi.sh) 仅覆盖 U8 与 FullNoneMixedChain 基线，按范围追加精确测试及 UI 验收。模型按目标环境已批准配置核验，不固定跨环境模型，不自行切换配置。

## 状态与文档权威

- 任务与合入状态：Gitea Issue / PR（单一来源）。
- CURRENT / FEATURE-MATRIX：只读历史快照（2026-09-29 起不再要求会话同步）。
- 发布门禁：[gap-matrix](./.doc/remediation/gap-matrix.md)，以有日期、提交和制品身份的证据作判断。
- 问题与修复：[问题台账](./.doc/audit/ISSUES.md)；开发注意事项：[经验库](./.doc/ops/lessons/INDEX.md)。
- 问题与方案：[audit](./.doc/audit/INDEX.md)、[remediation](./.doc/remediation/INDEX.md)。

## 凭证与推送

推送模型（2026-09-29 起）：dev/test/main 受 Gitea 保护——用户白名单身份可直推；编码 Agent 以 `agent-bot` 身份推送功能分支并建 PR，不直推主干。凭证查找 `${HOME}/.secrets/gitea`（weichen）与 `${HOME}/.secrets/agent-bot`（agent-bot），所需字段为 `ACCESS_TOKEN`。不向用户索要值，不把凭证写入仓库/git config；缺失只记录路径与缺字段。[git-push-dev.sh](./scripts/git-push-dev.sh) 仅适用于用户白名单直推场景。