---
project: <项目名>
processVersion: 2
lang: zh # zh / en —— 流程语言：门禁脚本、工具输出、角色技能都按它选语言；换语言改成 en 并同步把本文件译成英文
---

# 项目适配（PROJECT）

> 本文件是**通用流程与本项目之间的唯一接口**：通用文档（总纲 / 调度手册 / 模板）只引用本表，**不硬编码项目细节**。
> 换项目 = 只改本文件；通用流程文件**不得**因项目不同而被改写。
> **填写要求**：把每个 `<...>` 占位符替换为本项目的真实取值；未启用的可选项写「不适用」并给一句理由。
> **机器读取约定**（§4 / §5）：键名与取值按表格逐行读取，**键名照抄、不得改名**；取值用反引号包裹，多个用 `、` 分隔，**值内不要出现空格，也不要出现 `|`**（空格会被当成分隔符切碎，`|` 会截断表格列；正则请写成等价的无空格、无竖线形式）；未列出的键会被忽略。

---

## 1. 端与目录

> 登记本项目的全部「端 / 关键目录」：**一个端一行**，写清它是什么、代码在哪、谁可以写。
> 通用文档里的 `<app-a>` / `<app-b>` 等占位符，一律以本表取值代入。

| 端/目录 | 说明 | 可写角色 |
| --- | --- | --- |
| `<app-a>/` | <例如：后端 API 服务；技术栈一句话> | `<role-dev>` |
| `<app-b>/` | <例如：Web 管理后台；技术栈一句话> | `<role-dev>` |
| `<app-c>/` | <例如：移动端 H5；技术栈一句话> | `<role-dev>` |
| `<test-dir>/` | <例如：集成测试目录；由谁维护> | `<role-test>` |
| `<e2e-dir>/` | <例如：端到端 / 操作脚本目录；由谁维护> | `<role-uat>` |
| `docs/process/` | 流程目录（框架约定保留此路径，**不要改名**） | `<role-orchestrator>` |
| `docs/process/tools/` | 过程载体目录（一次性脚本 / 探针 / 截图；不进版本库） | `<role-test>` · `<role-uat>` |
| `<协调板>` | <并行会话协调板路径：一行一条 `ID · session · 时间 · 本包落点 · 占用资源`；含共享构建通道 / 真机 / 数据库等互斥资源。总纲 §2.7> | 全体（先比对落点交集，再登记后使用） |

---

## 2. 命令槽

> 通用流程只认这**四个用途**，不认具体命令；命令由本表提供。**固定的四行，不得增删用途、不得改名**。
> 每行写「用途 → 命令 → 说明」；命令用反引号原样可执行，说明写清退出码口径。

| 用途 | 命令 | 说明 |
| --- | --- | --- |
| 快速验证 | `<快速验证命令>` | <例如 `npm run check`。口径 = **本次验证无红**；任何一段报红即如实上报，禁止用白名单 / 排除 / 取错退出码等手段把红报成绿；跑在哪个基线必须声明。**跑完以 `action:"run"` + `command` + 真实 `exitCode` 落一条 journal** —— Gate 摘要的「🔒 本轮门禁证据」段只认它，不认「跑过了」这句话> |
| 产物落点门禁 | `<产物落点门禁命令>` | <判定"会进下一次提交"的**新增**文件是否落在属主表路径内；唯一放行来源 = `docs/process/tools/README.md` 登记区的登记行。三种模式：默认 = 未跟踪（**`git add` 之后就看不见了**）· `--staged` = 暂存区新增（提交前最后一道）· `--committed[=<rev>]` = 事后审计已入库提交新增；**受检 0 个时只报 ⚠ 空转、不打绿**> |
| 台账门禁 | `<台账门禁命令>` | <校验台账与用例配对（`@case` 存在且 `@status=active`）、`@prd` 归属、版本一致性、import 白名单> |
| journal 追加 | `<journal 追加命令>` | <追加式写入 `prd/<ID>.journal.jsonl`；锁 + 指纹校验 + 原子替换；**禁止读-改-写**；`at` 取机器时间；**门禁执行记录必带退出码**（总纲 §7 第 8 条）> |

> **命令槽与真命令必须同时改**：只改文档不改命令等于没改（真正执行的是命令）。
>
> **命令不会自己去留痕**：每条门禁跑完，由主控补一条 `action:"run"` 记录（命令原样 + 真实退出码）—— 否则 Gate 摘要只显示「未记录」，人没法判断这次到底跑没跑。
>
> **分层验证不新增固定槽位**：L1 = dev 用测试器自带过滤（不落槽）；L2 = 上表「快速验证」按包范围执行；L3 = 同一测试命令的全量写法 / 发布级组合（项目在「说明」里写明）。**不要为分层增删本表的四行**；范围写法由项目约定（如 `--scope package` / 目录过滤）。

---

<!-- process:owner-table -->
## 3. 产物属主表

> 每角色**唯一合法写入根**；越界即停，不得自行发明路径。
> 路径以仓库根为基准书写；属主写成角色名（与角色定义文件一致）。
> **机器读取约定**：`check-artifact-paths` 只取**「可写路径」列**作为允许写入的路径表，支持 `**` 跨目录通配与 `dir/` 目录前缀；「禁止」列仅供人阅读。
> **变量路径不要写 `<...>`**：含 `<` 或 `>` 的条目一律被当成「没替换的占位符」丢掉（这是刻意的，见下条），所以 `scripts/<ID>-<用途>.ts` 这类写法**不会生效**。要表达变量就用 `*` 通配（如 `scripts/*-*.{ts,sql}`），或者干脆不写进本表、改为在登记区**逐件登记**（更严格，推荐用于批次脚本）。
> **未填 = 未配置**：含 `<` 或 `>` 的条目被视为占位符、**不放行任何路径**；``` 代码块内部一律不参与解析。若「可写路径」列解析不到任何有效条目，门禁**报错退出 1，绝不静默放行**。

| 角色 | 可写路径 | 禁止 |
| --- | --- | --- |
| `<角色>` | `<路径>/**` | `<禁止>` |

> **示例（照抄后必须把 `<...>` 换成真实路径；本块不参与机器解析）**：
> 下表只是写法示范，**不是**本项目的配置 —— 门禁不会读取代码块内部的任何内容。

```markdown
| 角色 | 可写路径 | 禁止 |
| --- | --- | --- |
| `<role-orchestrator>`（主控） | `docs/process/README.md` · `docs/process/orchestrator.md` · `docs/process/PROJECT.md` · `docs/process/input/**` · `docs/process/ui/**`（框架落地的 UI 默认层：tokens / recipe） · `docs/process/experts/**`（框架落地的领域专家预设卡） · `docs/process/tools/README.md`（登记区） · `docs/process/prd/*.journal.jsonl*` · `scripts/process/**`（框架自带门禁 / journal / 初始化脚本，常驻） · `reports/orchestrator/**` | 写实现 / 写测试 / 替人做 Gate 决策 |
| `<role-pm>` | `docs/process/prd/**` · `docs/process/contracts/**` · `docs/process/input/<ID>-prior-art.md` · `docs/process/uat/<ID>-checklist.md` · `reports/pm-review/**` | 读业务实现 / 测试 / e2e / 日志；写实现 |
| `<role-architect>` | `docs/process/input/<ID>-tech-scan.md` · `docs/process/prd/<ID>-arch.md` · `reports/architect/**` | 读业务逻辑实现；写 PRD / 契约 / AC / 测试 / 源码；复制外部代码或引入依赖 |
| `<role-ui-designer>` | `docs/process/prd/<ID>-ui-spec.md` · `docs/process/prototypes/<ID>/**` · `reports/ui-review/**` | 改生产实现源码；读后端实现 / 前端组件内部实现 / 测试 / e2e / 日志；写其它角色产物 |
| `<role-test>` | `<test-dir>/packages/<ID>/**` · `<test-dir>/fixtures/<ID>-*` · `docs/process/rules/**` · `reports/test/**` · `docs/process/tools/<ID>/**` | 改 `src`；读业务实现细节（签名 / schema 除外） |
| `<role-dev>` | `<app-a>/src/**` · `<app-b>/src/**` · `<app-c>/src/**` · `scripts/<ID>-<用途>.{ts,sql}`（仅生产迁移 / 运维脚本，且须先登记） | 改 `test/` · 改 `e2e/` |
| `<role-uat>` | `docs/process/uat/**` · `reports/uat/**`（含 `evidence/`） · `<e2e-dir>/**` | 读任何代码 / 测试 / 日志；判功能对错以外的事 |
| `<role-domain-expert>` | `reports/experts/**` · `reports/domain-review/**` | 改 PRD / 设计 / UI 规格 / 原型 / 测试 / 源码；替持证专业人士下结论 |
| `<role-logic-review>` · `<role-code-review>` · `<role-security-review>` | `reports/<角色>/**` | 改 `src`；贴大段代码 |
```

> **`input/**` 不是主控独占**：核对件与 `research-brief` 归主控，`prior-art` 归 pm，`tech-scan` 归 architect；三者各写各的文件，**并行不等于共写**。**`prd/**` 里的 `<ID>-arch.md` 归 architect**，其余 PRD / 契约 / 设计与说明归 pm；主控只落状态位。落点门禁按属主**并集**放行，纪律上仍**单人属主**。

> **状态位例外（必须写进 §3）**：`prd/<ID>.md` 的 frontmatter 里 `status` / `gate0` / `gate1` / `gate2` / `gate4` 由**主控**在各 Gate 落定 —— 总纲要求「Gate 通过后落状态位」，**只把 `prd/**` 判给 pm 会让这条规则无法同时满足**（实例验收里就出现了一轮：状态位由主控写入，而属主表没判给主控），而且判据 ⑫（越界事后判定）会把主控落状态位**误判成越界**。其余内容（PRD 正文 / 契约 / checklist）仍属 `<role-pm>`。写法二选一：主控行补 `docs/process/prd/<ID>.md`（并写明「仅状态位」），或在此处明确例外条款。

> **`journal.jsonl` 后面那个 `*` 不能省**：journal 追加会旁挂一个 `<ID>.journal.jsonl.meta.json` 指纹文件（锁与指纹校验要用）。只写 `*.journal.jsonl` 时，只要项目把 pm 行收窄成 `prd/*.md`（§3 明说变量路径用 `*` 通配，这是很自然的写法），**框架自己的 audit 文件就会被框架自己的落点门禁判越界**。口径：**拥有 journal 的那一行必须自己覆盖它**，不能靠别人的 `prd/**` 顺带兜住。
> 注意：这条说明只能写在这里 —— **别把含 `<...>` 的备注写进路径单元格**，那会让整条路径被当成未替换的占位符丢掉。

**禁止落点（任何角色一律不得写入）**：

- 一次性探针 / 夹具播种 / 清理 / 截图 / 取证脚本落到受版本控制的 `scripts/` 根层 ⇒ 归 `docs/process/tools/<ID>/`；
- `scripts/` 下**未在载体侧登记区登记**的任何新文件；
- `docs/process/` 根层级（只放总纲 · 调度手册 · 本文件与四份模板）；
- 任何**未被忽略规则覆盖**的一次性产物（它一定会进人的提交）——「用完即删」不构成豁免。

---

## 4. 项目配置

> 本节是**门禁脚本的项目专属配置**入口：`check-rules.mjs` / `sync-prd-version.mjs` 读本节的测试目录与台账位置，`check-artifact-paths.mjs` 读本节的登记区文件，`check-ui-prototype.mjs` 读本节的 UI 原型目录。**每一行都可选**，删掉整行即用默认值；取值用反引号、多个用 `、` 分隔、值内不含空格。
> **未填 = 未配置**：取值列的 `<...>` 是占位符，**不填就拿到「说明」列承诺的默认值**；含 `<` 或 `>` 的取值一律被脚本忽略（示例值只写在「说明」列里，不参与解析）。``` 代码块内部不参与解析。
> **不得写死技术栈假设**：命令、目录、类型词表全部由本表提供，脚本只做确定性的读与判定。

| 配置项 | 取值 | 说明（默认值 / 示例 / 是否可选） |
| --- | --- | --- |
| 测试扫描目录 | `<目录>` | 可选，默认 `test`（示例：`test`）。`check-rules` 递归扫描测试的根目录，多个用 `、` 分隔；路径以仓库根为基准 |
| 测试文件后缀 | `<后缀>` | 可选，默认 `.test.ts`、`.test.mjs`、`.test.js`（示例：`.test.ts`、`.test.mjs`）。`check-rules` 与 `sync-prd-version` 据此识别测试文件（后者只认本节「需求包测试目录」下的文件） |
| 流程测试目录 | `<目录>` | 可选，默认与「测试扫描目录」相同（示例：`test`）。落在这些目录下的测试受「import 白名单」约束 |
| 需求包测试目录 | `<目录>` | 可选，默认 `test/packages`（示例：`test/packages`）。需求专属测试的家：每个包一个子目录 `<目录>/<ID>/`；归档批次豁免 git 跟踪过滤、但**只有该包仍有台账时才扫**；`sync-prd-version` 也在此定位 `<ID>` 的测试文件 |
| import 白名单 | `<正则>` | 可选，默认 `^node:`、`^https?:`、`^\.\.?/`、`^vitest$`、`^@?vitest`、`^jest$`、`^@jest/`、`^mocha$`、`^express$`、`^supertest$`（示例：`^node:`、`^\.\.?/`、`^@app/api`、`^@app/db`）。每项是一条**正则**，匹配 import 说明符（helpers / schema / routes 等合规入口在此登记） |
| 自动化类型 | `<类型>` | 可选，默认 `vitest`、`jest`、`node`、`junit`、`cdp`、`manual`、`uat`、`none`、`pending`、`withdrawn`（示例：`vitest`、`cdp`、`manual`、`none`、`pending`、`withdrawn`）。台账 `automation:` 的**精确**词表，取值不在表内即判 ❌ |
| @case 载体类型 | `<类型>` | 可选，默认 `vitest`、`jest`、`node`、`junit`（示例：`vitest`）。这些类型必须在源码里有 `@case TC-<ID>` 载体（其余类型免 `@case`，但应声明 `carrier:`） |
| junit 测试目录 | `<目录>` | 可选，默认不扫（示例：`mobile/android/app/src/test`）。配置后递归扫 `.java` 里的 `@case`（跳过 `build/`）作为 junit 载体 |
| 待裁定字样 | `<正则>` | 可选，默认 = 两个分支的交替正则（`以 Q-\d+ 裁定为准` 与 `或 HTTP \d+`，用竖线连接）（示例：`以Q-\d+裁定为准`）；本表单元格不能含竖线，自定义多分支请拆成等价单分支或直接删掉本行用默认。PRD 冻结（`status: frozen` / `gate2: approved`）后不得在 test 存活的字样正则 |
| 台账目录 | `<目录>` | 可选，默认 `docs/process/rules`（示例：`docs/process/rules`）。`<ID>.yaml` 台账所在目录 |
| PRD 目录 | `<目录>` | 可选，默认 `docs/process/prd`（示例：`docs/process/prd`）。`<ID>.md` 与 `<ID>-design.md` 所在目录 |
| 登记区文件 | `<路径>` | 可选，默认 `docs/process/tools/README.md`（示例：`docs/process/tools/README.md`）。`check-artifact-paths` 读取其 `## 登记区` 小节里以反引号登记过的路径（登记即放行） |
| UI 项目令牌 | `<路径>` | 可选，默认不配（示例：`web/src/styles/tokens.css`、`tailwind.config.ts`）。**项目已有的主题 / 设计令牌 / 设计系统包的位置**（多个用 `、` 分隔）。配了它 ⇒ UI 设计**必须先照抄这份令牌**，不得自创配色与间距；不配 ⇒ 回落到 `docs/process/ui/tokens.md` 的通用默认值。**两者不可混用**：同一包内一半抄项目、一半用默认，比全用默认更糟。**配了它 ⇒ 门禁 ⑩ 会判**：从这份令牌源里抽出色板（CSS 变量 / 散落色值都认），要求画面主色**全部**能由该色板推导出来（允许色板内两色按任意 α 叠加）；采到「用了整套别的色板」判 ❌。未配 ⇒ ⑩ 只 ⚠ 提示 |
| UI 原型目录 | `<目录>` | 可选，默认 `docs/process/prototypes`（示例：`docs/process/prototypes`）。每个包一个子目录 `<目录>/<ID>/`：**`index.html`（交付主件入口） + `styles.css` + `handoff.md`**；`check-ui-prototype` 据此判定。PNG/PSD 不是本流程的交付物 |

> **放行来源二选一说明**：产物落点门禁的放行 = §3「可写路径」列 **或** 本节「登记区文件」的登记区；两者都没有的一次性文件一律判 ❌。

---

## 5. UAT 前置自检

> 本节是 `check-uat-readiness.mjs` 的项目专属配置入口：填完后 UAT 派单前先跑一次，确认「环境 + 验收账号 + 目标端点 + 清单」就绪。
> **每一行都可选**；**命令行参数优先级高于本节**（同名 `--core` / `--web` / `--mobile` / `--account` / `--password` / `--api-prefix` / `--login-path` / `--token-field` / `--cdp` / `--checklist-dir` / `--evidence` 覆盖本表）。
> 未配置「验收账号」或「目标端点」时，对应检查**降级为 ⚠**（不崩溃、不误判为就绪）。
> **未填 = 未配置**：取值列的 `<...>` 是占位符，**不填就拿到「说明」列承诺的默认值**；含 `<` 或 `>` 的取值一律被脚本忽略（示例值只写在「说明」列里，不参与解析）。

| 配置项 | 取值 | 说明（默认值 / 示例 / 是否可选） |
| --- | --- | --- |
| core 后端 | `<URL>` | 可选，默认 `http://127.0.0.1:3000`（示例：`http://127.0.0.1:3000`）。后端存活探测，以及登录 / 目标端点探测的基地址 |
| web 前端 | `<URL>` | 可选，默认 `http://127.0.0.1:5173`（示例：`http://127.0.0.1:5173`）。Web 前端存活探测 |
| 移动端 | `<URL>` | 可选，默认 `http://127.0.0.1:5174`（示例：`http://127.0.0.1:5174`）。移动端存活探测（亦可用浏览器移动视口） |
| 验收账号 | `<账号>` | 可选，默认不配（跳过登录与端点权限探测）（示例：`uat_demo`）。只登记**测试账号**，禁写生产账号 |
| 验收口令 | `<口令>` | 可选，默认不配（示例：`uat-demo-pass`）。与「验收账号」配套；**只写来源或测试口令**，不得写生产明文 |
| 目标端点 | `<端点段>` | 可选，默认不配（跳过）（示例：`users?pageSize=1`、`roles`）。相对「端点前缀」的端点段列表；登录成功 ≠ 有权限，逐段要求 HTTP 200 |
| 端点前缀 | `<前缀>` | 可选，默认 `/api/v1`（示例：`/api/v1`）。拼在 `core 后端` 之后 |
| 登录路径 | `<路径>` | 可选，默认 `<端点前缀>/auth/login`（示例：`/api/v1/auth/login`）。POST `{account,password}`，期望 200 |
| 令牌字段 | `<点号路径>` | 可选，默认 `data.accessToken`（示例：`data.accessToken`）。登录响应里取 token 的**点号路径** |
| 真机 CDP | `<URL>` | 可选，默认 `http://localhost:9222/json`（示例：`http://localhost:9222/json`）。不通只 ⚠ 不阻断 |
| 清单目录 | `<目录>` | 可选，默认 `docs/process/uat`（示例：`docs/process/uat`）。其中 `<ID>-checklist.md` **缺失即判阻断**（UAT 会直接退回） |
| 证据目录 | `<目录>` | 可选，默认不配（`--progress` 时报 ⚠）（示例：`docs/process/reports/uat/evidence`）。统计 `U-NN-*` 证据文件数得到逐项完成度 |

> **`--pkg <ID>` 无默认值、必填**（命令行传入）；其余参数均可省略，缺省即回落到本表或脚本内置默认值。
> `--progress` 额外打印 UAT 逐项完成度（清单 `### U-<NN>` 项 ↔ 证据 `U-NN-` 前缀文件）。
>
> **环境生命周期归主控**：启动服务 / 装依赖 / 迁移种子 / 基线快照 / 健康检查由主控托管并登记；dev 只负责因本次改动而变的环境（schema 同步 / 新依赖 / 迁移脚本）。派单前未就绪 ⇒ 不派 dev。

---

## 6. 环境与凭据

> 只登记**位置与获取方式**，**不写明文密钥**。

| 项 | 取值 / 路径 | 说明 |
| --- | --- | --- |
| 服务地址（本地） | `<http://127.0.0.1:PORT>` | <各端端口一览> |
| 数据库 | `<连接串来源：环境变量名 / .env 键名>` | <本地库名；schema 变更纪律：只改 schema 源文件，迁移由人负责> |
| 测试账号 | `<seed 命令 / 凭据文件路径>` | <验收账号按角色分列，写清园区 / 权限前提；禁改共享账号数据> |
| 真机 / 设备 | `<设备标识 / 驱动端口>` | <占用登记方式：claim / release / TTL；占用未释放不得派单> |
| 凭据文件 | `<uat 凭据文件路径>` | <长期保留、非批次产物；不进版本库> |
| 忽略规则 | `<.gitignore 相关条目>` | <哪些过程路径被忽略，避免误判"没进 git = 没做"> |

---

## 7. 通知（**已废弃，编号保留**）

> 本框架不再有通知渠道：Gate 就在对话里，「人不在场」的场景不覆盖。**本节整节写「不适用」**；保留编号只为避免全文 §1–§7 的引用错位。
