cgraphx 1.2.0 → 1.3.0

package/dist/.claude-template/skills/write-api/assets/template-request.bru

@@ -0,0 +1,75 @@
+meta {
+    name: <场景名,如 正常 / 缺prodInstId / 产品不存在>
+    type: http
+}
+
+# HTTP 方法段:get / post / put / delete / patch
+# 查询接口示例(get):
+get {
+    url: {{baseUrl}}/api/v1/users/:id
+    body: none
+}
+
+# 写接口示例(post,取消注释切换):
+# post {
+#     url: {{baseUrl}}/api/v1/users
+#     body: json
+# }
+
+params:query {
+    # 查询参数,写真实值(AI 从 DB 查或代码推断),不变量化
+    # expand: true
+    # ~disabled_param: value    # ~ 前缀表示禁用此参数
+}
+
+params:path {
+    # 路径参数,写真实值(如 id: 12345),不变量化
+    # 唯一例外:前置接口动态传递的值可用 {{var}}
+    # id: {{test_user_id}}
+    id: 12345
+}
+
+headers {
+    Content-Type: application/json
+    # 鉴权 header 由 AI 在 S3 根据项目既有 .bru 和 environments/local.bru 的变量名对齐后追加
+    # 不同项目鉴权方式不同(accesstoken/staffcode/regionid 或 Authorization/X-API-Key 等)
+    # 不在此硬编码示例,避免 AI 套模板;AI 必须按目标项目实际生成
+}
+
+# 请求体(写接口用,查询接口删此段):
+# 入参写真实值(AI 从 DB 查或代码推断),不变量化
+# 唯一例外:前置接口动态传递的值可用 {{var}}
+# body:json {
+#     {
+#         "name": "测试用户",
+#         "email": "test@example.com",
+#         "phone": "13800000000"
+#     }
+# }
+
+# 测试脚本:用项目既有 bruno 版本支持的语法
+# 既有语法:test("name", function() { ... }) + res.getStatus() / res.getBody()
+# 不要用 function onResponse(request, response) 新语法
+# 不要用 assert 段(项目 bruno 版本可能不支持),断言全放 tests
+tests {
+    test("HTTP 200", function() {
+        expect(res.getStatus()).to.equal(200);
+    });
+
+    test("响应体关键字段", function() {
+        const body = JSON.parse(res.getBody());
+        expect(body.code).to.equal(0);
+        expect(body.data).to.exist;
+    });
+
+    # 写接口额外写 DB 副作用预期注释,供 S6 AI 核实参考:
+    # DB 预期:users 表新增一行,name=测试用户,email=test@example.com
+    # DB 预期:user_profile 表同步新增一行,user_id=本次返回的 id
+}
+
+docs {
+    业务说明: <一句话,从 Javadoc 或 spec 提取;提取不到占位"(scan 阶段未提取到 Javadoc,请补充业务说明)">
+
+    关联需求:
+    - <YYYY-MM-DD-feature-id> (<文件前缀>-spec.md)
+}

package/dist/.claude-template/skills/write-api/references/ai-prompts.md

@@ -0,0 +1,133 @@
+# AI Prompt 指引(S2 + S3)
+
+## S2 微服务识别 prompt 指引
+
+### 输入
+
+AI 在 S2 生成测试规格时,先读以下上下文:
+- 项目结构:顶层目录、`package.json` / `pom.xml` / `go.mod` 等包描述
+- `docs/bruno/` 既有子目录(避免命名漂移)
+- 本次接口清单(S1 拿到)
+- 接口路径前缀
+
+### 判断
+
+AI 判定每个接口归属的服务名,或判定为"无服务划分"。
+
+判断依据:
+- 项目根有 `services/` / `apps/` / `packages/` 等多模块目录 → 每个一级子目录视为一个服务,子目录名作服务名
+- 接口路径前缀含服务名标识(如 `/so-assist-service/openapi/xxx`)→ 取路径段作服务名
+- 单体项目无明显服务边界 → 判定为"无服务划分"
+
+### 跨 feature 一致性
+
+AI 识别时**优先参考 `docs/bruno/` 既有服务目录名**,避免同一服务在不同 feature 间命名漂移。
+
+例:既有 `docs/bruno/so-assist-service/`,新接口也属该服务,就用 `so-assist-service`,不新取 `so-assist`。
+
+### 输出
+
+结果写入测试规格 §1 接口清单的"服务"列:
+- 有服务归属 → 填服务名
+- 无服务划分 → 填 `-` 或 `(无)`
+
+用户可在 S3 前手动校正此列。
+
+---
+
+## S2 通用接口判断 prompt 指引
+
+### 输入
+
+AI 在 S2 判断每个接口是否通用时,读:
+- 接口路径
+- 接口语义(从代码或 spec 拿)
+- `docs/bruno/common/` 既有接口(避免重复生成)
+
+### 判断
+
+AI 判定是否"通用接口"——跨 feature 复用的前置接口归为通用:
+
+| 类型 | 例 |
+|---|---|
+| 登录 / token 刷新 | `/auth/login`、`/auth/refresh` |
+| 健康检查 | `/health`、`/healthcheck`、`/actuator/health` |
+| 公共字典 | `/common/dict`、`/common/enum` |
+| 公共枚举 | 系统级枚举查询 |
+
+### 跨 feature 一致性
+
+AI 判断时**优先参考 `docs/bruno/common/` 既有接口**,避免重复生成。
+
+例:`common/login/` 已存在,新 feature 的登录接口不重复生成,直接复用。
+
+### 输出
+
+结果写入测试规格 §1 接口清单的"通用"列:`yes` / `no`。
+
+`yes` 的接口,S3 落盘时归 `docs/bruno/common/<接口名>/`,不绑 feature。
+
+用户可在 S3 前手动校正此列。
+
+---
+
+## S3 生成 .bru prompt 指引
+
+### 单次调用约束
+
+**单次 AI 调用生成全部 .bru**——不拆两阶段(先程序化骨架后 AI 增强),不逐接口循环。
+
+理由:
+- 拆两阶段会让 AI 在第二阶段重新读一遍上下文,浪费 token
+- 逐接口循环在接口多时上下文丢失,生成质量下降
+- 单次调用让 AI 看全局,断言一致性更好
+
+### 输入
+
+- 接口清单(S1)
+- 测试规格文档(S2 产出)
+- 代码上下文:通过 `codegraph_explore` 拿 handler 源码、参数定义、默认值、必填项
+- DB 数据:通过 `db-query` 查真实可用数据
+
+### 输出
+
+每个接口的**每个场景**一个 `.bru` 文件,符合 `bru-format.md` 规范:
+- `meta { name, type: http }`
+- HTTP 方法段 + `params` + `headers` + `body:json`(写接口)
+- `tests { test("name", function() { ... }) }` 内嵌断言(旧版语法)
+- `docs { 业务说明 / 关联需求 spec 列表 }`
+
+### 拿不到真实数据时
+
+AI 在以下情况拿不到真实数据:
+- DB 无相关数据(表空 / 无匹配 id)
+- 代码无可推断默认值(参数是用户输入型,如 `phone`、`email`)
+
+处理:
+1. 在 .bru 留 `{{var}}` 占位
+2. 在测试规格 §3 标注该参数"需用户手填"
+3. **不因此中断**,继续生成其他能生成的 .bru
+
+理由:部分参数没值不代表整个 feature 不能跑测试;能跑的部分先跑,漏的让用户补。
+
+### 失败处理
+
+AI 调用失败(超时 / 限流):
+- 报"AI 增强失败"
+- 保留已生成的测试规格(S2 产出)
+- **不继续 S4**(环境准备)
+
+理由:S3 没出 .bru,S4 准备环境也没意义;让用户判断是重跑 write-api 还是手动调整。
+
+---
+
+## 跨步骤约束
+
+### 降级处理
+
+| 项目状态 | S3 降级行为 |
+|---|---|
+| 未接入 cgraphx 索引 | S3 用 grep + Read 兜底拿 handler 源码,精度可能下降;在测试规格 §4 标注 |
+| 未配置 db-query profile | S3 留 `{{var}}` 占位 + 测试规格 §4 标注"DB 查询不可用";后续 `/run-api-test` 的 R4 也会降级,标"无法核实" |
+
+降级不中断 skill,继续跑能跑的部分。

package/dist/.claude-template/skills/write-api/references/api-spec-format.md

@@ -0,0 +1,108 @@
+# S2 测试规格文档格式规范
+
+## 六节结构(必须完整)
+
+测试规格文档 `<文件前缀>-api-spec.md` 必须含以下六节,顺序固定:
+
+### §1. 接口清单
+
+```markdown
+## 1. 接口清单
+
+| 方法 | 路径 | handler | 服务 | 通用 | 是否写接口 |
+|---|---|---|---|---|---|
+| GET | /api/v1/users/:id | UserController.getUser | user-service | no | 否 |
+| POST | /api/v1/users | UserController.create | user-service | no | 是 |
+| POST | /api/v1/auth/login | AuthController.login | - | yes | 是 |
+```
+
+- **服务**列:由 AI 在 S2 判断(见 `ai-prompts.md` §S2 微服务识别),无服务划分时填 `-` 或 `(无)`
+- **通用**列:由 AI 在 S2 判断(见 `ai-prompts.md` §S2 通用接口判断),值为 `yes` / `no`
+- 用户可在 S3 前手动校正这两列,skill 以校正后为准
+
+### §2. 测试场景
+
+每个接口列正常 / 边界 / 异常场景:
+
+```markdown
+### GET /api/v1/users/:id
+- 正常场景:存在 id,返回 200 + 用户详情
+- 边界场景:id 不存在,返回 404
+- 异常场景:id 格式非法,返回 400
+```
+
+### §3. 测试数据
+
+按场景列参数,标注获取方式(代码提取 / DB 查询 / AI 推断 / 用户手填):
+
+```markdown
+### GET /api/v1/users/:id
+| 场景 | 参数 | 值 | 获取方式 |
+|---|---|---|---|
+| 正常 | id | 12345 | DB 查询(users 表取已有 id) |
+| 不存在 | id | 999999 | AI 推断 |
+```
+
+- 标"用户手填"的参数:在 .bru 里留 `{{var}}` 占位,跑前需用户填
+- 获取方式决定 S3 生成 .bru 时参数从哪取
+
+### §4. 数据获取方式
+
+汇总本 feature 测试数据来源 + 指明哪些需用户确认 / 补充 + 降级说明:
+
+```markdown
+本 feature 测试数据来源:
+- 代码提取:从 handler 源码拿默认值、必填项、参数类型
+- DB 查询:通过 db-query skill 查 users 表取真实 id;查 inst_attr 表取真实 attr_id
+- AI 推断:组装符合校验规则的测试值(手机号、邮箱格式等)
+- 用户手填:以下参数需用户在跑前确认或补充:
+  - {{token}}:登录 token
+  - {{admin_user_id}}:管理员用户 id
+
+降级说明(仅在降级时填,正常情况删):
+- 未接入 cgraphx:S3 用 grep + Read 兜底,参数提取精度可能下降
+- 未配置 db-query:S3 留 {{var}} 占位,S6 DB 核实标"无法核实"
+```
+
+### §5. 接口映射
+
+场景 → 接口 → .bru 文件路径,路径指向 `docs/bruno/` 下的实际位置:
+
+```markdown
+| 场景 | 接口 | .bru 文件路径 |
+|---|---|---|
+| GET /api/v1/users/:id 正常 | GET /api/v1/users/:id | docs/bruno/user-service/getUser/正常.bru |
+| POST /api/v1/users 缺必填 | POST /api/v1/users | docs/bruno/user-service/createUser/缺name.bru |
+| POST /api/v1/auth/login 正常 | POST /api/v1/auth/login | docs/bruno/common/login/正常.bru |
+```
+
+- 路径规则见 `collection-layout.md`
+- 此映射是下游 `/run-api-test` R1 拿 .bru 清单的来源,必须写全
+
+### §6. 验收口径
+
+明确什么算通过、什么不算:
+
+```markdown
+通过:
+- 查询接口:HTTP 200 + 断言通(响应体关键字段符合预期)
+- 写接口:HTTP 2xx + 断言通 + DB 核实通(数据真的写了/改了/删了,字段值正确)
+- 通用接口:同查询/写接口规则
+
+不算通过:
+- HTTP 200 但断言失败 → 失败-断言
+- HTTP 200 + 断言通但 DB 数据错 → 失败-DB副作用
+- 4xx / 5xx → 失败-HTTP
+- 超时 / connection refused(服务就绪后)→ 失败-连接
+```
+
+## 模板
+
+完整填充示例见 `assets/template-api-spec.md`,AI 生成时以它为骨架填充。
+
+## 与下游 skill 的契约
+
+- §1 的"服务"和"通用"列 → 驱动 S3 .bru 落盘路径(见 `collection-layout.md`)
+- §3 的获取方式 → 驱动 S3 参数填充策略(见 `bru-format.md` 入参规则)
+- §5 的映射 → 下游 `/run-api-test` R1 拿 .bru 清单的来源,必须与实际 .bru 文件一一对应(否则 `/run-api-test` 会报"对应 .bru 缺失")
+- §4 的降级说明 → 让用户和下游 skill 知道哪些核实会降级

package/dist/.claude-template/skills/write-api/references/bru-format.md

@@ -0,0 +1,144 @@
+# S3 .bru 文件格式规范
+
+## 各段结构(必须含)
+
+每个 .bru 符合 bruno-lang v2 语法,段顺序固定:
+
+```
+meta {
+    name: <场景名,如 正常 / 缺prodInstId / 产品不存在>
+    type: http
+}
+
+# HTTP 方法段:get / post / put / delete / patch
+get {
+    url: {{baseUrl}}/api/v1/users/:id
+    body: none
+}
+
+# 写接口示例:
+# post {
+#     url: {{baseUrl}}/api/v1/users
+#     body: json
+# }
+
+params:query {
+    # 查询参数,写真实值
+}
+
+params:path {
+    # 路径参数,写真实值(如 id: 12345)
+    # 唯一例外:前置接口动态传递的值用 {{var}}
+    id: 12345
+}
+
+headers {
+    Content-Type: application/json
+    # 鉴权 header 由 AI 按项目既有 .bru + environments/local.bru 的变量名对齐后追加
+    # 不同项目鉴权方式不同(accesstoken/staffcode/regionid 或 Authorization/X-API-Key 等)
+    # 不在此硬编码示例,避免 AI 套模板
+}
+
+# 写接口的请求体(查询接口删此段):
+# 入参写真实值,不变量化
+# body:json {
+#     {
+#         "name": "测试用户",
+#         "email": "test@example.com"
+#     }
+# }
+
+tests {
+    # 用旧版 tests 语法(见下方"断言语法")
+}
+
+docs {
+    # 见下方"docs 段写法"
+    业务说明: <一句话>
+
+    关联需求:
+    - <YYYY-MM-DD-feature-id> (<文件前缀>-spec.md)
+}
+```
+
+## 断言语法(必须用旧版)
+
+**必须用** `test("name", function() { ... })` + `res.getStatus()` / `res.getBody()` 旧版语法——这是项目既有 bruno 版本支持的写法,新版语法 `function onResponse(request, response)` 不认。
+
+**不要用** `assert { ... }` 段——项目 bruno 版本可能不支持,断言全放 `tests` 段。
+
+断言内容:
+
+```bru
+tests {
+    test("HTTP 200", function() {
+        expect(res.getStatus()).to.equal(200);
+    });
+
+    test("响应体关键字段", function() {
+        const body = JSON.parse(res.getBody());
+        expect(body.code).to.equal(0);
+        expect(body.data).to.exist;
+    });
+
+    # 写接口额外写 DB 副作用预期注释,供下游 /run-api-test 的 R4 AI 核实参考:
+    # DB 预期:users 表新增一行,name=测试用户,email=test@example.com
+    # DB 鄄期:user_profile 表同步新增一行,user_id=本次返回的 id
+}
+```
+
+### 断言内容要求
+
+- **HTTP 状态码断言** — 每个场景都要(正常场景通常 200/201,异常场景可能 400/404/409)
+- **响应体关键字段断言** — 从 spec 接口语义或代码返回结构提取,用 `JSON.parse(res.getBody())` 取 body
+- **写接口额外写 DB 副作用预期注释** — 用 `#` 注释,写预期会写/改/删哪些表哪些字段,供 `/run-api-test` R4 AI 核实参考
+
+## 入参写真实值,不变量化
+
+接口入参(如 `prodInstId`)优先写 AI 从 DB 查到或代码推断的**真实值**,直接写死在 `body:json` / `params` 段里。
+
+**不变量化的理由**:入参是测试数据,每次跑测试应该用具体值才能稳定复现;变量化只用于"跨环境或跨接口的动态值"。
+
+`{{var}}` 占位**只在以下三种情况使用**:
+
+| 场景 | 说明 |
+|---|---|
+| 环境级变量 | `baseUrl`、服务端口、鉴权凭据等 → 写在 `environments/local.bru` 里,.bru 用 `{{var}}` 引用 |
+| 前置接口动态传递 | 登录 token、前接口返回 id 等 → 用 `vars:post-response` 段提取,.bru 用 `{{var}}` 引用 |
+| AI 拿不到真实值 | DB 无数据、代码无可推断默认值时 → 留 `{{var}}` 占位 + 测试规格 §3 标注"需用户手填" |
+
+第 3 种情况发生时,在测试规格 §3 标注哪些参数需用户手填,skill 继续跑能跑的部分,不因此中断。
+
+## docs 段写法(固定结构)
+
+```
+docs {
+    业务说明: <一句话,从 Javadoc 或 spec 提取;提取不到占位"(scan 阶段未提取到 Javadoc,请补充业务说明)">
+
+    关联需求:
+    - <YYYY-MM-DD-feature-id> (<文件前缀>-spec.md)
+}
+```
+
+### 关联需求列表的行为
+
+- AI 生成时,若该接口目录下已有 .bru(docs 段含历史关联需求),把当前 feature-id **追加**到列表(去重),不删除已有 feature
+- 不在 docs 段写断言推理 / 场景预期等详细内容(简短,bruno 不渲染 markdown)
+- **关联需求列表是 `/run-api-test` 反查"接口关联哪些 feature"的依据**——用户触发 `/run-api-test` 只指定接口时,AI 反查此列表让用户选测哪个 feature;列表必须写全,不能漏
+
+## header 名 / 变量名对齐
+
+AI 生成 headers 段时,必须先看项目既有 .bru 的 header 名和 `{{var}}` 变量名大小写(如 `accesstoken` vs `accessToken`),避免大小写漂移导致 env 注入失败。
+
+不同项目鉴权方式不同:
+
+| 项目示例 | 鉴权 header |
+|---|---|
+| hx 项目 | `accesstoken` / `staffcode` / `regionid`(全小写) |
+| 其他项目 | 可能是 `Authorization: Bearer xxx` / `X-API-Key: xxx` 等 |
+
+AI 按目标项目实际探明,不套任何模板示例。
+
+## 模板
+
+完整骨架见 `assets/template-request.bru`。

package/dist/.claude-template/skills/write-api/references/collection-layout.md

@@ -0,0 +1,81 @@
+# S3 .bru collection 目录组织规范
+
+## 目录结构
+
+```
+docs/bruno/
+├── bruno.json                       # 根级,bruno app 靠此识别整个 docs/bruno/ 为 collection
+├── environments/                    # bruno 原生运行时环境配置(见 environment-setup.md)
+│   ├── local.bru
+│   ├── staging.bru
+│   └── production.bru
+├── common/                          # 通用接口,跨服务跨 feature 复用
+│   └── <接口名>/
+│       └── <场景>.bru
+└── <服务名>/                        # 微服务,无服务划分时退化为此层不存在
+    └── <接口名>/                    # 接口目录,跨 feature 累积场景
+        ├── <场景-1>.bru
+        └── <场景-2>.bru
+```
+
+## 路径规则
+
+| 接口类型 | 路径 |
+|---|---|
+| 业务接口(有服务划分) | `docs/bruno/<服务>/<接口名>/<场景>.bru` |
+| 业务接口(无服务划分) | `docs/bruno/<接口名>/<场景>.bru` |
+| 通用接口 | `docs/bruno/common/<接口名>/<场景>.bru` |
+
+### 取名规则
+
+- **`<服务>`** — 由 AI 在 S2 识别(见 `ai-prompts.md`),参考 `docs/bruno/` 既有目录名保持一致
+- **`<接口名>`** — 取接口的方法名或路径最后一段,参考项目既有 .bru 的命名习惯
+- **`<场景>`** — 取测试规格 §2 的场景名(如 `正常` / `缺prodInstId` / `产品不存在`)
+
+## 按接口组织,不绑 feature-id
+
+**核心原则**:接口跨 feature 复用,按 `<接口名>` 组织目录,**不绑 feature-id**。
+
+不同 feature 测同一接口时,往同一接口目录追加场景 .bru,而不是按 feature-id 分目录。理由:同一接口的测试应该集中管理,方便跨 feature 回归。
+
+## 跨 feature 同接口同场景覆盖
+
+不同 feature 测同一接口的同一场景时,**后跑的覆盖先跑的 .bru**。
+
+理由:测哪个需求就从当前需求 spec + DB 重新取数据,不保留历史入参(历史入参会过时,留着误导)。
+
+**例外**:docs 段的"关联需求"列表**不覆盖**,而是去重追加——记录该接口关联过哪些 feature,供 `/run-api-test` 反查。
+
+## 不生成 per-folder collection.bru
+
+bruno 的 folder 不需要 `collection.bru`,只在 `docs/bruno/` 根级有一个 `bruno.json`(见下方)。
+
+## 根级 bruno.json
+
+若 `docs/bruno/bruno.json` 不存在,生成:
+
+```json
+{
+  "version": 1,
+  "name": "<project>-api-test",
+  "type": "collection"
+}
+```
+
+`<project>` 取项目根目录名(如 `hx`、`zq` 等)。
+
+已存在则**不覆盖**,沿用用户配置。
+
+## 首次接入
+
+项目首次接入时,`docs/bruno/` 不存在,skill 自动创建:
+
+- `docs/bruno/` 目录
+- `bruno.json`
+- `environments/` 目录(见 `environment-setup.md`)
+
+不报错,不需要用户手动准备。
+
+## 与测试规格文档的契约
+
+测试规格 §5 接口映射里的路径必须与实际落盘路径**一一对应**,否则下游 `/run-api-test` R1 拿到 .bru 清单后会报"对应 .bru 缺失"。

package/dist/.claude-template/skills/write-api/references/environment-setup.md

@@ -0,0 +1,105 @@
+# S4 bruno 环境配置规范
+
+## 文件位置与格式
+
+```
+docs/bruno/environments/
+├── local.bru          # 本地环境(默认)
+├── staging.bru        # 测试环境
+└── production.bru     # 生产环境
+```
+
+每个 .bru 是 bruno 原生运行时格式,`vars { ... }` 段:
+
+```
+vars {
+    <服务名或baseUrl>: http://127.0.0.1:<端口>
+    <非敏感业务变量>: <值>
+    <鉴权变量1>:
+    <鉴权变量2>:
+}
+```
+
+环境名固定三档,英文:`local` / `staging` / `production`(避免命令行传中文编码问题)。
+
+## 首次接入生成逻辑
+
+`docs/bruno/environments/local.bru` 不存在时,skill 生成三个 .bru 文件骨架,然后:
+
+### non-secret 变量(AI 填)
+
+AI 扫项目配置(pom.xml / package.json / application.yml / go.mod 等)探明端口,填入 `local.bru`:
+- 服务的地址变量(如 `so-assist: http://127.0.0.1:8087`)
+- region、租户等非敏感业务变量
+
+`staging.bru` / `production.bru` 的 non-secret **留空**,提示用户填(避免 AI 瞎猜外部环境地址)。
+
+### secret 变量(AI 决定字段名,值留空)
+
+AI 看项目既有 .bru 的**鉴权 header 名**决定有哪些 secret 字段:
+
+- 若既有 .bru 用 `accesstoken` / `staffcode` / `regionid` → secret 字段就是这些名
+- 若既有 .bru 用 `Authorization` / `X-API-Key` → secret 字段就是 `Authorization` / `xApiKey`
+- 不固定 hx 的字段名,其他项目不同
+
+**值留空**,字段加 `secret: true`(bruno-environment 格式支持;bruno 原生 .bru 格式无 secret 标记,值留空即可,bruno app 里手动标 secret)。
+
+### 生成后暂停
+
+skill 暂停提示用户:
+
+```
+环境配置已生成骨架:
+- docs/bruno/environments/local.bru(non-secret 已填,secret 留空)
+- docs/bruno/environments/staging.bru(全空)
+- docs/bruno/environments/production.bru(全空)
+
+请填 local.bru 的 secret 变量(staffcode/accesstoken 等),填完回车继续。
+```
+
+不直接结束,等用户填完回车。
+
+## 已存在不覆盖
+
+`docs/bruno/environments/local.bru` 已存在 → 沿用,**不重写**。
+
+理由:用户可能已经手动调过端口或 secret,重写会覆盖用户配置。
+
+## 环境切换
+
+- 默认 `local`
+- 用户调用 `/run-api-test --env staging` 切换,透传 `bru run --env staging`
+- write-api 阶段不跑 bru run,所以 write-api 不关心环境切换;环境切换是 `/run-api-test` 的事
+
+## 不自动生成 secret 的理由
+
+**为什么 secret 不自动填值**:AI 不应该接触真实 token / 密码 / API key——
+1. 避免泄露,skill 资产或日志可能记录
+2. AI 无法知道真实值(这些值通常是用户从浏览器、运维系统手动取的)
+3. 让用户明确填一次,后续 `environments/local.bru` 沿用,不需要每次跑都填
+
+## 模板示例(参考,不照搬)
+
+hx 项目 local.bru 示例(变量名 + 值都是 hx 特定,AI 生成时按目标项目实际探明,**不套此模板**):
+
+```
+vars {
+    so-assist: http://127.0.0.1:8087
+    regionid: 8323300
+    staffcode:
+    accesstoken:
+}
+```
+
+其他项目可能长这样(AI 按 zq 项目探明):
+
+```
+vars {
+    baseUrl: http://127.0.0.1:8080
+    zqassis: http://127.0.0.1:8080
+    Authorization:
+    xApiKey:
+}
+```
+
+变量名和端口都从项目实际探明,不预设。