weichen
8bc7940ee0
Align prepared clients with role budgets and automatic approvals. Keep uncertain delivery from triggering duplicate work and preserve task worktree gates.
55 lines
3.9 KiB
Markdown
55 lines
3.9 KiB
Markdown
# Agent-System 项目入口
|
||
|
||
工作边界见 [AGENTS.md](./AGENTS.md)。本仓库是 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 严格隔离，禁止跨环境读写。
|
||
|
||
创建任务、合入、环境写操作与清理前读 [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 验收。模型按目标环境已批准配置核验，不固定跨环境模型，不自行切换配置。
|
||
|
||
## 状态与文档权威
|
||
|
||
- 活跃工作/协调快照：[CURRENT](./.doc/ops/CURRENT.md)。
|
||
- 能力声明与剩余条件：[FEATURE-MATRIX](./.doc/status/FEATURE-MATRIX.md)。
|
||
- 发布门禁：[gap-matrix](./.doc/remediation/gap-matrix.md)，以有日期、提交和制品身份的证据作判断；项目入口不缓存“无 blocker”或当前 schema。
|
||
- 问题与方案：[audit](./.doc/audit/INDEX.md)、[remediation](./.doc/remediation/INDEX.md)。
|
||
- 规范状态与生效版本：[规范登记](./.doc/ops/2026-09-21-policy-registry.md)。
|
||
|
||
## 凭证与推送
|
||
|
||
用户明确授权 push/同步远端后，使用 [git-push-dev.sh](./scripts/git-push-dev.sh) 的分支参数；先核对目标分支。凭证查找 `${HOME}/.secrets/gitea`，所需字段为 `ACCESS_TOKEN` 与 `URL_PREFIX`（文件按脚本支持格式填写）。不向用户索要值，不把凭证写入仓库/git config；缺失只记录路径与缺字段。
|
||
|
||
## Herdr 工程协作
|
||
|
||
仅在明确使用 Herdr 编排/启动/派发时读 [角色、审批与备援 SSOT](./.doc/ops/2026-09-13-herdr-agent-roster.md)；使用 [启动脚本](./scripts/herdr-agent-start.sh) / [派发脚本](./scripts/herdr-agent-dispatch.sh)。此时按 v1.2 资源预算与角色路由执行；普通 Codex/Claude/Cursor 会话不套用该分工。`context_pi` 是协作终端的 PI CLI，不能替代产品 PI Agent Runner 验收。实际客户端/模型/在线状态记录在本次运行证据中。
|