张胜宇
bc61d5c579
## 为什么做这一步 权威文档 74 份此前**只在本机**，评审者 clone 分支后看不到任何设计文档；而仓库里那两份同名目录 是 **2026-09-16 之前的过期副本，连文件名都是旧的**（无体系编号）。本次按「**权威覆盖过期**」入库。 ## 入库内容 | 目录 | 文件数 | 体积 | 说明 | |---|---|---|---| | `客服agent/` | 24 | 0.77 MB | `D2.1`~`D2.6` 对外交付四件套 + 演示脚本/答辩报告 + `_build` 构建工具 | | `开发文档/` | 50 | 2.16 MB | `D1.x` 索引与决策、`D3.x` 方案、`D4.x` 清除与重构留痕、`D5.x` 业务流程、`D6.x` 业务事实基座、`D7.x` 交付物、`D8.x` 规范 | **旧的过期副本整体移除**（`客服Agent执行Todolist.md` → `D2.1-客服Agent执行Todolist.md` 之类 的改名 + 新增 `D2.5`/`D2.6`），入库后目录内容与权威副本**逐文件一致（零差异，已复核）**。 ## 入库前的安全扫描（必须留痕） - 扫描规则：`sk-` 类密钥 / `Bearer` 长串 / `password=`、`api_key=` 赋值 / 会话中出现过的两把明文 key 片段。 - 结论：**真实密钥只出现在 `.env`**（已被 `.gitignore` 命中，未入库）；`.env.example` 与 `config/risk.env.example` 只有**空占位**。 - 文档内唯一命中是 `D3.1` 里一处**截断的示例 JWT**（`Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...`）， 末尾带省略号，是接口文档的示意值，**不是可用凭据**。
66 lines
3.7 KiB
Markdown
66 lines
3.7 KiB
Markdown
# 项目语言规范
|
||
|
||
> **体系编号**：`D8.1` · 域：八、AI 协作规则 · 编号体系见 `D1.1` §4.0
|
||
> **日期**：2026-09-19 · **性质**：**强制规范**（人机协作与交付物的语言口径，开工前必读）
|
||
> **来源**：本文件原以「`D8.1` 项目语言规范」为题**内嵌在 `开发文档\CLAUDE.md` 顶部**（与英文本的 AI 入口协议同处一文件）。按 `乙-27` / `DEC-28` 裁定「做 `D8.1-项目语言规范.md` + 三行存根」，现拆分为独立文件；`CLAUDE.md` 只留指向本文件的存根。
|
||
|
||
## 1. 四条硬规则（对话与全部产出）
|
||
|
||
| # | 规则 | 适用面 |
|
||
|---|---|---|
|
||
| 1 | 所有对话、解释、建议必须使用**简体中文** | 人机对话、方案、评审意见 |
|
||
| 2 | 代码注释必须使用中文 | `app\`、`tools\`、`tests\` 全量源码 |
|
||
| 3 | 生成的 Commit Message 必须使用中文 | git 提交信息 |
|
||
| 4 | 严禁出现**大段未翻译的英文技术名词** | 全部交付文档与代码注释 |
|
||
|
||
> **术语例外（不构成违规）**：技术标识符与命令名（`Milvus`、`pytest`、`nffund.com`、`Idempotency-Key`）、行业标准缩写（`RAG`、`RBAC`、`Embedding`、`DoS`）、库名与字段名**一律保留原文**；判定标准是**成句的英文**——整句英文描述必须译为中文。
|
||
|
||
## 2. AI 协作入口协议（原 `CLAUDE.md` 正文，2026-09-19 迁入）
|
||
|
||
### 2.1 规则优先级
|
||
|
||
**P0 阅读规范 → P1 项目上下文 → P2 执行规范 → P3 测试规范 → P4 输出规范**；发生冲突时按同序裁决（前者优先）。
|
||
|
||
| 优先级 | 文件 |
|
||
|---|---|
|
||
| P0 阅读 | `开发文档\ai\D8.3-01_READING_RULES.md` |
|
||
| P1 上下文 | `开发文档\ai\D8.7-05_PROJECT_CONTEXT.md` |
|
||
| P2 执行 | `开发文档\ai\D8.4-02_EXECUTION_RULES.md` |
|
||
| P3 测试 | `开发文档\ai\D8.5-03_TESTING_RULES.md` |
|
||
| P4 输出 | `开发文档\ai\D8.6-04_OUTPUT_RULES.md` |
|
||
|
||
### 2.2 强制工作流（禁止跳过阅读阶段直接编码）
|
||
|
||
理解需求 → 阅读项目 → 建立上下文 → 分析影响面 → 输出方案 → 获得确认（如需） → 实现 → 测试 → 总结。
|
||
|
||
### 2.3 阅读完成闸门（八问，任一答不上就继续阅读）
|
||
|
||
① 当前需求属于哪个模块？② 当前调用链是什么？③ 当前数据从哪里来？④ 当前数据写到哪里去？
|
||
⑤ 当前权限在哪里校验？⑥ 当前影响哪些模块？⑦ 当前风险等级是什么？⑧ 最小修改方案是什么？
|
||
|
||
### 2.4 高风险区域（必须先完成风险分析，**禁止直接修改**）
|
||
|
||
`Docker` / `Docker Compose` / `Nginx` / 环境变量 / 数据库迁移 / 认证 / `RBAC` / 文件存储 / 后台 `Worker` / 部署脚本 / `CI`、`CD`。
|
||
|
||
### 2.5 编码准入条件
|
||
|
||
已完成：项目阅读 + 调用链分析 + 影响面分析 + 方案设计 + 明确验证方案。**缺任一项则继续阅读。**
|
||
|
||
### 2.6 项目哲学
|
||
|
||
AI 的首要职责不是写代码，而是**理解项目**：理解错误则后续全部错误，理解正确则编码只是执行。
|
||
**`Reading First. Coding Later.`**
|
||
|
||
## 3. 编号与落位（2026-09-19 起）
|
||
|
||
| 文件 | 编号 | 位置 | 性质 |
|
||
|---|---|---|---|
|
||
| 项目语言规范（本文件） | `D8.1` | `开发文档\D8.1-项目语言规范.md` | 强制规范（正文） |
|
||
| 用法说明 | `D8.2` | `开发文档\ai\D8.2-README.txt` | 说明〔`.txt` 例外，不注入编号行〕 |
|
||
| 阅读 / 上下文 / 执行 / 测试 / 输出 | `D8.3`—`D8.7` | `开发文档\ai\` | 分层规范 |
|
||
| 入口存根 | — | `开发文档\CLAUDE.md` | **仅三行**，指向本文件 |
|
||
|
||
---
|
||
|
||
**维护**：语言口径变更须改本文件并同步 `D1.1` §4.0 总表；`CLAUDE.md` 保持三行存根，**不得再在其内追加规则正文**（否则又回到「同一规范两处正文」）。
|