From 245b8c9a81023b26d90f2fd519f2eb767fc0b64b Mon Sep 17 00:00:00 2001 From: zlwu <704541015@qq.com> Date: Mon, 2 Nov 2026 09:19:54 +0800 Subject: [PATCH] =?UTF-8?q?docs(agents):=20=E5=8C=BA=E5=88=86=E5=BA=94?= =?UTF-8?q?=E7=94=A8=E8=BF=90=E8=A1=8C=E5=87=AD=E6=8D=AE=E4=B8=8E=20Agent?= =?UTF-8?q?=20=E6=93=8D=E4=BD=9C=E8=B4=A6=E5=8F=B7?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 避免排障时把管理账号写进应用配置，操作账号只从本工程授权来源按需读取。 Co-authored-by: Cursor --- AGENTS.md | 1 + .../specs/architecture-conventions/spec.md | 16 ++++++++++++++++ 2 files changed, 17 insertions(+) diff --git a/AGENTS.md b/AGENTS.md index f965abda..dcc71944 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -26,6 +26,7 @@ - 用户明确“我来测试”时，该任务由用户测试：Agent 不运行测试或构建，仍完成代码审查和 Git 核对；交付时提醒切换到具体分支，提供 worktree 路径、提交、前后端配套入口和验证要点。用户确认通过后直接合并推送、关闭工单；未确认或失败时不合并、不关闭。 - 合并前核对验收提交与最新目标；目标更新或冲突处理改变代码时，按原测试责任补验，用户模式仍交用户验证。合并后代码树与验收版本一致不重复测试；确认远端同步成功后回写验收结果、合并提交和 PR 并关单。 - 不把真实凭据、业务导出、虚拟环境、构建产物和工具临时状态新增到版本管理。 +- 配置或使用账号时，按[运行凭据与 Agent 操作凭据](openspec/changes/zkxw-engineering-standards/specs/architecture-conventions/spec.md#requirement-运行凭据与-agent-操作凭据分离)区分来源：应用沿用自己的环境配置，`.local/secrets/access.json` 仅供 Agent 操作使用。 - 清理文件前核查代码、测试、脚本、部署及文档引用；不能只凭名称、日期或搜索无结果删除。 ## 跨端数据与权限底线 diff --git a/openspec/changes/zkxw-engineering-standards/specs/architecture-conventions/spec.md b/openspec/changes/zkxw-engineering-standards/specs/architecture-conventions/spec.md index cff0fc76..a266f5c2 100644 --- a/openspec/changes/zkxw-engineering-standards/specs/architecture-conventions/spec.md +++ b/openspec/changes/zkxw-engineering-standards/specs/architecture-conventions/spec.md @@ -37,3 +37,19 @@ - **WHEN** 提交涉及 Web 或小程序界面的 PR - **THEN** PR 或关联 OpenSpec SHALL 声明遵循的 UI 规范文档路径 + +### Requirement: 运行凭据与 Agent 操作凭据分离 + +应用运行凭据 SHALL 继续由对应应用的 `.env`、配置文件或部署环境注入管理，包括数据库、Redis、MinIO、业务微信接口及应用签名或加密密钥。现有 `backend/.env`、`backend/.env.production`、`deploy/docker/.env` 等来源按实际环境使用，不为统一账号保存位置而迁移或复制其中的值。 + +工程根目录 `.local/secrets/access.json` SHALL 仅用于 Agent 操作账号，如服务器 SSH、GitHub/Gitea 仓库管理及 Figma 平台访问；它不是应用运行配置源，不接入业务代码或容器启动配置。可用的 MCP、OAuth、CLI 会话继续复用，不为填文件重复索要密码。应用排障按需读取原运行配置，不使用平台管理账号替换应用身份。 + +Agent 使用操作账号前 SHALL 核对当前工程、服务用途、环境和任务授权，只读取所需字段；服务器测试与生产账号分开。该文件不纳入 Git、镜像、交付包或更新器，目录权限为 `700`、文件为 `600`（macOS/Linux）；不得在聊天、日志或工单回显真实值。worktree 缺文件时仅核对并复用同仓库主工作目录的已授权来源，不能跨工程搜集或自动回退生产。 + +#### Scenario: 应用数据库认证失败 +- **WHEN** 后端连接数据库失败，而操作账号文件中有其他管理账号 +- **THEN** 核对后端实际加载的环境配置及其账号，不把管理账号写入运行配置，也不改为读取操作账号文件。 + +#### Scenario: Agent 访问仓库或设计平台 +- **WHEN** 已授权任务需要 Gitea、GitHub 或 Figma 身份认证 +- **THEN** 优先复用可用工具会话；需要账号时从本工程操作账号来源按需读取，仅缺失或无效时补充，不改动应用运行配置。