# 配置你的仓库

插件本身不需要配置。要配置的是**你仓库里的流程**，而唯一的接口是 `docs/process/PROJECT.md`。

## 唯一接口：PROJECT.md

通用文档（`docs/process/README.md` 总纲、`orchestrator.md` 调度手册、`skills/**` 角色技能）只**引用** `PROJECT.md`，不硬编码任何具体项目的路径、命令与凭据。这带来两个承诺：

- **升级插件不会覆盖你填的 PROJECT.md**；
- **换项目只需重填 PROJECT.md**。

### 七个小节

| 节 | 内容 |
|---|---|
| §1 端与目录 | 本项目有哪些端（前端/后端/移动端…）、各自源码目录、并行会话协调板路径 |
| §2 命令槽 | 每类动作对应的命令（跑测试、起服务、打验收包…） |
| §3 产物属主表 | 哪些路径是可写落点、由哪个角色负责 |
| §4 项目配置 | 语言、包管理器、测试框架、自动化类型等取值 |
| §5 UAT 前置自检 | 真机验收前必须先满足的条件 |
| §6 环境与凭据 | 需要哪些环境变量与凭据 |
| §7 通知 | **已废弃**（编号占位，写「不适用」） |

## 语言（zh / en）

流程本身支持中英两种语言，语言是**仓库级**设定，不是插件级：

| 顺序 | 来源 | 怎么改 |
|---|---|---|
| 1 | 环境变量 `PROCESS_KIT_LANG` | `PROCESS_KIT_LANG=en dsh web`（进程级临时覆盖，排障用） |
| 2 | `docs/process/.process-kit.json` 的 `lang` | `process_init({ upgrade: true, lang: "en" })` 自动写；也可手改 |
| 3 | `docs/process/PROJECT.md` frontmatter 的 `lang` | 直接改这一行 |
| 4 | 按 `AGENTS.md` / `README.md` 的语言推断 | 无需配置 |
| 5 | 都没有 ⇒ `zh` | 存量仓库零变化 |

`process_init` 的 `lang` 参数接受 `zh` / `en` / `auto`（默认 `auto`：清单 → 仓库文档 → `zh`）。

**换语言**：`process_init({ upgrade: true, lang: "en" })`。框架自有文件（总纲 / 调度手册 / 模板 / 门禁脚本）按新语言覆盖、覆盖前备份为 `<文件>.bak-<时间戳>`；`PROJECT.md` / `ui/tokens.md` / `ui/recipe.md` 属于项目可定制文件，**不会被覆盖**，只会报告「需人工比对」并给出包内新语言版本的位置。

**门禁怎么认两种写法**：模板在关键小节上方放机器标记（`<!-- process:owner-table -->` / `<!-- process:registry -->`）；标记缺失时回退中英标题别名（`## 3. 产物属主表` / `## 3. Artifact ownership`、`## 登记区` / `## Registry`）；§4 / §5 的配置键中英都认（如 `台账目录` 与 `Rules dir`）。**标记不要删**——它是唯一不随文字漂移的锚点。

**维护纪律**：改任一语言都要同轮改另一种；`npm test` 里的 `test/i18n.test.mjs` 会核对两套骨架文件清单一致、英文侧零中文残留、配置键对照表三方一致，以及在英文仓库里两道门禁能跑到绿。完整契约见 [I18N.md](./I18N.md)。

## 未填 = 未配置（占位符纪律）

模板里所有 `<...>` 都是**会被脚本忽略**的占位符。这是硬口径，不是建议——因为「假绿比红更危险」：

- **§3 可写路径**：含 `<` 或 `>` 的条目**一票不放行**。如果整列解析不到任何有效条目，落点门禁会**报错退出 1**，绝不静默放行。
- **§4 / §5 取值**：含 `<` 或 `>` 的取值视为未配置，**回落到「说明」列承诺的内置默认值**。因此模板里的示例值永远不会覆盖默认配置。
- **代码块内部不参与解析**：模板里的完整示例都放在围栏代码块里，照着抄不会污染机器读取。
- **变量路径别写 `<...>`**：用 `*` 通配（如 `scripts/*-*.{ts,sql}`），或者干脆不写进 §3、改在登记区**逐件登记**——后者更严格，推荐用于批次脚本。

## 门禁与流程脚本

`process_init` 会往你的仓库落一份脚本副本（零依赖，只用 `node:` 内置模块，可直接 `node` 跑）：

| 脚本 | 作用 |
|---|---|
| `journal-append.mjs` | 安全追加 journal（锁 + 指纹校验 + 原子替换 + **链式指纹 `chainHash`**：能发现任意一行被改 / 删行 / 换行，不只是末行） |
| `check-artifact-paths.mjs` | 校验产物是否落在 §3 允许的路径内 |
| `check-rules.mjs` | 校验流程规则（Gate、状态位、属主表、台账 ↔ 测试互引）；含**越界事后判定**（角色边界，fail-open） |
| `check-ui-prototype.mjs` | 校验 HTML 原型交付：`index.html` / `data-ui` 覆盖 / `handoff.md` / 外部网络 / 本地链接；**只判交接完整性，不判审美** |
| `sync-prd-version.mjs` | 同步 PRD 版本号 |
| `project-config.mjs` | 上面几个脚本共用的 PROJECT.md 解析件（含中英锚点别名表 `SECTION` / `HEADER` / `CONFIG_KEYS`） |
| `i18n.mjs` | 语言判定（`resolveLang`）与成对取词器（`makeMsg`）；上面几个脚本共用 |

> **脚本是项目自带副本，不随插件升级自动更新。** 插件修了门禁逻辑之后，要跑一次 `process_init(upgrade: true)` 把这些脚本与 `docs/process/tools/README.md` 同步过去。
>
> **升级到带链式指纹的版本时**：旧副本写出的 `.meta.json` 没有 `chainHash`，读取侧会如实报「⚠ 旧格式：只验了行数与末行」——**不会误报篡改**，跑一次 `process_init(upgrade: true)` 之后新写入的记录即带链式指纹。

## 上下文是怎么进入会话的

AGENTS.md 那条老路（harness 读工作区指令文件）和插件不是替代关系，而是互补的三层：

| 层 | 载体 | 作用域 | 内容 |
|---|---|---|---|
| 框架级常驻 | 插件注册的 systemPrompt 段 | 该 profile 下**所有**工作区与 subagent | 7 行硬提醒：先调 `process_status`、Gate 必须人签、两段式、journal 纪律、角色由插件技能提供、真源指向；首行同时提示 `process_uninstall` 的卸载路径 |
| 项目级常驻 | 仓库里的 `AGENTS.md` | 该仓库 | 指针：本项目流程真源在 `docs/process/README.md`、适配在 `PROJECT.md`；**不复述细则** |
| 按需注入 | 角色技能 / `docs/process/README.md` / `PROJECT.md` | 派单时或读到才进上下文 | 角色职责、状态机、Gate 格式、属主表 |

插件**替不了**第二层：插件是跨仓库的通用包，只有仓库自己才知道「本项目流程真源在哪」。所以 `process_init` 会保证它存在（只在缺失时创建，已存在则只打印待合并段落）。
