5.1 KiB
5.1 KiB
运行凭据与 Agent 操作凭据
先按用途区分凭据，不按“是否与工程有关”归到同一个文件：
| 用途 | 保存与读取位置 |
|---|---|
| 应用运行：数据库、Redis、MinIO、业务微信接口、应用签名或加密密钥 | 沿用各应用的 .env、运行配置或部署环境注入机制，由应用按现有方式读取 |
| Agent 操作：服务器 SSH、GitHub/Gitea 仓库管理、Figma 平台等账号 | 默认保存在当前工程根目录的 .local/secrets/access.json，供 Agent 在任务授权内按需读取 |
.local/secrets/access.json 不是应用配置源。不得为统一整理而把运行凭据迁入、复制进此文件，或让业务代码、容器启动配置自动读取它。应用认证失败时排查该应用实际加载的配置，不拿平台管理账号或另一环境的账号替换。临时排障确需使用应用凭据时，在任务授权内从原配置按需读取，不集中复制保存。
Agent 操作凭据已有明确的工程专用路径、外部密钥服务或已授权工具会话时继续沿用；可用的 GitHub/Figma MCP、OAuth 或 CLI 会话优先复用，不为填文件而索要密码。账号密码、令牌的选择由服务支持的认证方式决定。旧配置占位值 external-controlled-storage 不代表已设置外部服务。下面的本地文件约定仅针对 Agent 操作凭据，隐藏不等于加密。
使用前先查现有来源
- 先确认当前工程、目标服务、操作用途及环境，再核对 Agent 操作凭据的配置来源；未指定有效来源时检查上述默认路径。已有可用凭据直接在任务授权内复用，不重复索要。文件存在、字段非空不等于认证成功；缺失、为空或实际认证失败时，只询问缺少的相关信息，不猜测值。
- 在进程内解析文件并仅取本次所需字段，直接用于认证；不通过
cat、打印整个 JSON、命令行密码参数或带密码 URL 把内容暴露给聊天或工具输出。控制认证错误的输出，日志和工单仅记录成功/失败及脱敏原因。 - 测试和生产分开记录，明确选择目标环境，不能因为测试凭据缺失就回退生产。凭据存在只说明可尝试认证，不扩大部署、数据修改或生产操作授权。个人 Git 身份与应用服务身份分别记录和使用。
创建与维护
- 新工程安排 Agent 操作凭据来源或首次需要此类凭据时，先检查现有文件及防护。尚无文件时创建空模板，用户提供并要求保存的信息再写入对应条目；现有文件保留结构和无关字段，只更新指定内容，不用模板覆盖。文件或路径为未核实的符号链接时先核对来源，不跟随链接写入。
- 写入真实值前，核实
.local/secrets/被.gitignore排除，且文件不在 Git 索引中。核对所有能包含它的实际 Docker 构建上下文和生效的 ignore 文件（含 Dockerfile 专用 ignore），以及打包脚本、附件、备份和交付清单；按需要排除该目录。已跟踪的文件不能靠追加忽略规则变为未跟踪，先停止写入真实值并处理跟踪问题。 - 在 macOS/Linux 创建目录时即使用
700、创建文件时即使用600；维护时复核权限，写入临时文件也使用相同保护，避免先宽权限落盘再收紧。不更改工程根目录或其他服务的权限。其他系统核对等效访问控制，不能声称 POSIX 权限已生效。 - 可提交的
project.json、样例、文档仅记录来源路径、字段名和空值，不存真实账号密码。敏感文件不作为安装器受管资源、版本摘要、事务备份或更新上传内容；安装器当前只写来源说明，不自动创建此文件或替你完成 ignore/权限检查。Agent 在实际创建/使用阶段执行本节检查。
推荐按操作服务和服务器环境组织，下面只有空值；已有工程可保留自己的结构，不批量删除或迁移既有条目：
{
"schema_version": 1,
"project": "",
"purpose": "agent_operations_only",
"services": {
"gitea": {"url": "", "username": "", "password": "", "token": ""},
"github": {"url": "", "username": "", "password": "", "token": ""},
"figma": {"url": "", "username": "", "password": "", "token": ""},
"test": {"servers": []},
"production": {"servers": []}
}
}
Worktree 与换电脑
Git 不复制被忽略的 Agent 操作凭据文件。任务 worktree 中找不到此文件时，先用工程记录及 Git worktree 元数据确认同一仓库的主工作目录，在已有授权和配置指向下按需读取它的本地凭据；不批量扫描其他工程或自动复制整份凭据。若任务确需独立账号，另行配置并复核环境，不能把 worktree 隔离当作数据库隔离。
无法唯一定位同工程来源时说明缺口，请用户指定路径。换电脑也不会由 Git 或个人 Agent 更新器同步真实值，需要单独迁移或重新配置；只迁移所需条目并重新检查目标权限和忽略规则。读取或保存后仅报告路径、权限、忽略状态及缺失字段，不回显真实值。